docs.yml

---
name: docs

# Path-filtered SIMT lane (same roots as ci.yml).
on:
  push:
    branches: [main]
    paths:
      - 'cuda-oxide/**'
      - 'cuda-bindings/**'
      - 'cuda-core/**'
      - 'cuda-core-derive/**'
      - 'cuda-async/**'
      - 'Cargo.toml'
      - 'Cargo.lock'
      - '.github/workflows/**'
  pull_request:
    branches: [main]
    paths:
      - 'cuda-oxide/**'
      - 'cuda-bindings/**'
      - 'cuda-core/**'
      - 'cuda-core-derive/**'
      - 'cuda-async/**'
      - 'Cargo.toml'
      - 'Cargo.lock'
      - '.github/workflows/**'

# Each commit on main gets its own group, so it starts at once. Any other ref
# still shares one group and cancels the older run.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref_name }}${{ github.ref_name == 'main' && format('-{0}', github.sha) || '' }}
  cancel-in-progress: ${{ github.ref_name != 'main' }}

permissions:
  contents: read

# Gate rustdoc and doctests, which the `unit-tests` job does not cover (it runs
# `--lib --tests`, excluding doctests, and never builds docs). Keeps broken
# intra-doc links and uncompilable doc examples from accumulating silently.
jobs:
  rustdoc-and-doctests:
    name: cargo doc + doctests
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      - name: Install CUDA toolkit
        # `cargo doc --workspace` compiles cuda-bindings' build-time bindgen,
        # which needs `cuda.h`. Same toolkit pin as the unit-tests job.
        uses: Jimver/cuda-toolkit@3d45d157f327c09c04b50ee6ccdea2d9d017ec76  # v0.2.35
        id: cuda-toolkit
        with:
          cuda: "13.1.1"
          method: network
          sub-packages: '["nvcc", "cudart-dev"]'
          non-cuda-sub-packages: '["libcurand-dev"]'

      - name: Build docs (warning-free) and run doctests
        working-directory: cuda-oxide
        env:
          CUDA_TOOLKIT_PATH: ${{ steps.cuda-toolkit.outputs.CUDA_PATH }}
          RUSTDOCFLAGS: "-D warnings"
        run: |
          sysroot="$(rustc --print sysroot)"
          export LIBRARY_PATH="${sysroot}/lib:${LIBRARY_PATH:-}"
          export LD_LIBRARY_PATH="${sysroot}/lib:${LD_LIBRARY_PATH:-}"

          # Docs must build warning-free (RUSTDOCFLAGS=-D warnings above).
          cargo doc --no-deps --workspace

          # Run doctests.
          cargo test --doc --workspace

      # `rustc-codegen-cuda` is its own [workspace] (it links against
      # rustc-private dylibs), so `--workspace` above never reaches it. fmt,
      # clippy and unit-tests each carry a dedicated step for that crate;
      # this gate did not, which is how four broken intra-doc links in its
      # crate-level documentation went unreported.
      - name: Build docs (warning-free) for rustc-codegen-cuda
        working-directory: cuda-oxide/crates/rustc-codegen-cuda
        env:
          RUSTDOCFLAGS: "-D warnings"
        run: |
          sysroot="$(rustc --print sysroot)"
          export LIBRARY_PATH="${sysroot}/lib:${LIBRARY_PATH:-}"
          export LD_LIBRARY_PATH="${sysroot}/lib:${LD_LIBRARY_PATH:-}"
          cargo doc --no-deps