# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # # SPDX-License-Identifier: Apache-2.0 name: "CI: Build and update docs" on: workflow_call: inputs: component: description: "Component(s) to build docs for" required: false default: "all" type: string # below are the acceptable options: # - cuda-core # - cuda-bindings # - cuda-python # - cuda-pathfinder # - all git-tag: description: "Target git tag to build docs for" required: false default: "" type: string run-id: description: "The GHA run ID that generated validated artifacts" required: false default: ${{ github.run_id }} type: string is-release: description: "Are we building release docs?" required: false default: false type: boolean deploy-docs: description: "Deploy generated docs to GitHub Pages or preview branches" required: false default: true type: boolean docs-branch: description: "Branch that receives deployed docs" required: false default: "gh-pages" type: string jobs: build: name: Build docs # The build stage could fail but we want the CI to keep moving. if: ${{ github.repository_owner == 'nvidia' && !cancelled() }} runs-on: ubuntu-latest outputs: deployment-artifact-name: ${{ steps.deployment-metadata.outputs.deployment-artifact-name }} docs-github-ref: ${{ steps.deployment-metadata.outputs.docs-github-ref }} pr-number: ${{ steps.deployment-metadata.outputs.pr-number }} defaults: run: shell: bash -el {0} steps: - name: Checkout ${{ github.event.repository.name }} uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 1 ref: ${{ inputs.git-tag }} - name: Read build CTK version run: | if [[ -f ci/versions.yml ]]; then BUILD_CTK_VER=$(yq '.cuda.build.version' ci/versions.yml) elif [[ -f ci/versions.json ]]; then BUILD_CTK_VER=$(jq -r '.cuda.build.version' ci/versions.json) else echo "error: cannot find ci/versions.yml or ci/versions.json" >&2 exit 1 fi if [[ ! "${BUILD_CTK_VER}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then echo "error: derived CTK build version ${BUILD_CTK_VER} does not match MAJOR.MINOR.MICRO" >&2 exit 1 fi echo "BUILD_CTK_VER=${BUILD_CTK_VER}" >> "$GITHUB_ENV" # TODO: This workflow runs on GH-hosted runner and cannot use the proxy cache - name: Set up miniforge uses: conda-incubator/setup-miniconda@be893c923ea9cf1cf7cd510fbdde27c7e18cbdcb # v4.1.0 with: activate-environment: cuda-python-docs environment-file: ./cuda_python/docs/environment-docs.yml miniforge-version: latest conda-remove-defaults: "true" python-version: 3.12 - name: Check conda env run: | conda info conda list conda config --show-sources conda config --show # WAR: Building the doc currently requires CTK installed (NVIDIA/cuda-python#326,327) - name: Set up mini CTK uses: ./.github/actions/fetch_ctk with: host-platform: linux-64 cuda-version: ${{ env.BUILD_CTK_VER }} - name: Set environment variables run: | PYTHON_VERSION_FORMATTED="312" # see above REPO_DIR=$(pwd) # Release docs may check out tags from before the source-root rename. if [[ -d cuda_bindings_13 ]]; then CUDA_BINDINGS_SOURCE_DIR=cuda_bindings_13 elif [[ -d cuda_bindings ]]; then CUDA_BINDINGS_SOURCE_DIR=cuda_bindings else echo "error: cannot find the cuda.bindings source directory" >&2 exit 1 fi echo "CUDA_BINDINGS_SOURCE_DIR=${CUDA_BINDINGS_SOURCE_DIR}" >> "$GITHUB_ENV" if [[ ${{ inputs.is-release }} == "true" ]]; then FILE_HASH="*" DOCS_GITHUB_REF="${{ inputs.git-tag }}" if [[ -z "${DOCS_GITHUB_REF}" ]]; then DOCS_GITHUB_REF="${GITHUB_REF_NAME}" fi else FILE_HASH="${{ github.sha }}" DOCS_GITHUB_REF=$(python ci/tools/checkout_source_links.py --github-ref) fi # make outputs from the previous job as env vars CUDA_CORE_ARTIFACT_BASENAME="cuda-core-python${PYTHON_VERSION_FORMATTED}-linux-64" echo "CUDA_PYTHON_DOCS_GITHUB_REF=${DOCS_GITHUB_REF}" >> $GITHUB_ENV echo "CUDA_CORE_ARTIFACT_BASENAME=${CUDA_CORE_ARTIFACT_BASENAME}" >> $GITHUB_ENV echo "CUDA_CORE_ARTIFACT_NAME=${CUDA_CORE_ARTIFACT_BASENAME}-${FILE_HASH}" >> $GITHUB_ENV echo "CUDA_CORE_ARTIFACTS_DIR=$(realpath "$REPO_DIR/cuda_core/dist")" >> $GITHUB_ENV CUDA_BINDINGS_ARTIFACT_BASENAME="cuda-bindings-python${PYTHON_VERSION_FORMATTED}-cuda${BUILD_CTK_VER}-linux-64" echo "CUDA_BINDINGS_ARTIFACT_BASENAME=${CUDA_BINDINGS_ARTIFACT_BASENAME}" >> $GITHUB_ENV echo "CUDA_BINDINGS_ARTIFACT_NAME=${CUDA_BINDINGS_ARTIFACT_BASENAME}-${FILE_HASH}" >> $GITHUB_ENV echo "CUDA_BINDINGS_ARTIFACTS_DIR=$(realpath "$REPO_DIR/$CUDA_BINDINGS_SOURCE_DIR/dist")" >> $GITHUB_ENV - name: Download cuda-python build artifacts uses: $/.github/actions/download-artifact-retry with: name: cuda-python-wheel path: . run-id: ${{ inputs.run-id }} github-token: ${{ github.token }} - name: Display structure of downloaded cuda-python artifacts run: | pwd ls -lahR . - name: Download cuda-pathfinder build artifacts uses: $/.github/actions/download-artifact-retry with: name: cuda-pathfinder-wheel path: ./cuda_pathfinder run-id: ${{ inputs.run-id }} github-token: ${{ github.token }} - name: Display structure of downloaded cuda-pathfinder artifacts run: | pwd ls -lahR cuda_pathfinder - name: Download cuda.bindings build artifacts if: ${{ !inputs.is-release }} uses: $/.github/actions/download-artifact-retry with: name: ${{ env.CUDA_BINDINGS_ARTIFACT_NAME }} path: ${{ env.CUDA_BINDINGS_ARTIFACTS_DIR }} - name: Download cuda.bindings build artifacts if: ${{ inputs.is-release }} uses: $/.github/actions/download-artifact-retry with: pattern: ${{ env.CUDA_BINDINGS_ARTIFACT_NAME }} merge-multiple: "true" path: ${{ env.CUDA_BINDINGS_ARTIFACTS_DIR }} run-id: ${{ inputs.run-id }} github-token: ${{ github.token }} - name: Display structure of downloaded cuda.bindings artifacts run: | pwd ls -lahR $CUDA_BINDINGS_ARTIFACTS_DIR - name: Download cuda.core build artifacts if: ${{ !inputs.is-release }} uses: $/.github/actions/download-artifact-retry with: name: ${{ env.CUDA_CORE_ARTIFACT_NAME }} path: ${{ env.CUDA_CORE_ARTIFACTS_DIR }} - name: Download cuda.core build artifacts if: ${{ inputs.is-release }} uses: $/.github/actions/download-artifact-retry with: pattern: ${{ env.CUDA_CORE_ARTIFACT_NAME }} merge-multiple: "true" path: ${{ env.CUDA_CORE_ARTIFACTS_DIR }} run-id: ${{ inputs.run-id }} github-token: ${{ github.token }} - name: Display structure of downloaded cuda.core build artifacts run: | pwd ls -lahR $CUDA_CORE_ARTIFACTS_DIR - name: Install all packages run: | pushd cuda_pathfinder pip install *.whl popd pushd "${CUDA_BINDINGS_ARTIFACTS_DIR}" pip install *.whl popd pushd "${CUDA_CORE_ARTIFACTS_DIR}" pip install *.whl popd # Subpackages are already installed from CI artifacts above. # --no-deps avoids re-resolving cuda-core from PyPI during tag releases. pip install --no-deps cuda_python*.whl # PR CI uses pull-request/ refs regardless of the target branch. - name: Get PR number if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }} uses: ./.github/actions/get_pr_number - name: Mark latest docs build if: ${{ !inputs.is-release && !startsWith(github.ref_name, 'pull-request/') }} run: echo "BUILD_LATEST=1" >> "$GITHUB_ENV" - name: Record deployment metadata id: deployment-metadata run: | echo "deployment-artifact-name=docs-deployment-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT" echo "docs-github-ref=${CUDA_PYTHON_DOCS_GITHUB_REF}" >> "$GITHUB_OUTPUT" echo "pr-number=${PR_NUMBER:-}" >> "$GITHUB_OUTPUT" - name: Set up artifact directories run: mkdir -p artifacts/docs - name: Build all docs if: ${{ inputs.component == 'all' }} run: | pushd cuda_python/docs/ if [[ "${{ inputs.is-release }}" == "false" ]]; then ./build_all_docs.sh latest-only else ./build_all_docs.sh # At release time, we don't want to update the latest docs rm -rf build/html/latest # Nor the shared version-switcher file at the docs root: the theme # fetches it from one URL for every version, and main deploys own it. # A release built from a branch would overwrite it with a stale list. rm -f build/html/nv-versions.json build/html/versions.json fi ls -l build popd mv cuda_python/docs/build/html/* artifacts/docs/ - name: Build component docs if: ${{ inputs.component != 'all' }} run: | COMPONENT=$(echo "${{ inputs.component }}" | tr '-' '_') if [[ "${{ inputs.component }}" == "cuda-bindings" ]]; then COMPONENT="${CUDA_BINDINGS_SOURCE_DIR}" fi pushd ${COMPONENT}/docs/ if [[ "${{ inputs.is-release }}" == "false" ]]; then ./build_docs.sh latest-only else ./build_docs.sh # At release time, we don't want to update the latest docs rm -rf build/html/latest # Nor the shared version-switcher file at the docs root: the theme # fetches it from one URL for every version, and main deploys own it. # A release built from a branch would overwrite it with a stale list. rm -f build/html/nv-versions.json build/html/versions.json fi ls -l build popd if [[ "${{ inputs.component }}" != "cuda-python" ]]; then TARGET="${{ inputs.component }}" mkdir -p artifacts/docs/${TARGET} else TARGET="" fi mv ${COMPONENT}/docs/build/html/* artifacts/docs/${TARGET} # Check links and anchors in the rendered HTML built above. # Links in authored Markdown and reST files are checked separately by the # ordinary Linux/Windows pre-commit jobs. # The link-check action runs in a non-login shell, so give it a known # interpreter instead of the conda environment used above. - name: Set up Python for link checks if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }} uses: ./.github/actions/setup-hardened-python with: python-version: "3.14" - name: Check rendered documentation links through pre-commit if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }} timeout-minutes: 60 uses: ./.github/actions/lychee-links with: kind: rendered # Full CI's pull-request/N mirror supplies the PR number. pr-number: ${{ env.PR_NUMBER }} - name: Upload docs GitHub Pages artifact if: ${{ inputs.deploy-docs }} uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 with: path: artifacts/ retention-days: 3 - name: Upload docs deployment payload if: ${{ inputs.deploy-docs }} uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: ${{ steps.deployment-metadata.outputs.deployment-artifact-name }} path: artifacts/docs/ retention-days: 3 include-hidden-files: true if-no-files-found: error - name: Upload dry-run docs artifact if: ${{ !inputs.deploy-docs || (inputs.is-release && inputs.docs-branch != 'gh-pages') }} uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: release-docs-dry-run-${{ inputs.component }}-${{ inputs.git-tag }} path: artifacts/docs/ retention-days: 3 deploy: name: Deploy docs # GitHub discards prerequisite artifacts on a new run attempt. If only this # job fails, use "Re-run all jobs" so the build recreates its payload. needs: build if: ${{ inputs.deploy-docs && needs.build.result == 'success' }} runs-on: ubuntu-latest # Must match every job that writes to gh-pages. concurrency: group: cuda-python-gh-pages-publish queue: max cancel-in-progress: false defaults: run: shell: bash -el {0} steps: - name: Checkout ${{ github.event.repository.name }} uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 1 ref: ${{ inputs.git-tag }} - name: Download docs deployment payload uses: $/.github/actions/download-artifact-retry with: name: ${{ needs.build.outputs.deployment-artifact-name }} path: artifacts/docs/ - name: Deploy doc preview if: ${{ inputs.deploy-docs && !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }} uses: ./.github/actions/doc_preview with: source-folder: artifacts/docs pr-number: ${{ needs.build.outputs.pr-number }} - name: Deploy doc update if: ${{ inputs.deploy-docs && (github.ref_name == 'main' || inputs.is-release) }} uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0 with: git-config-name: cuda-python-bot git-config-email: cuda-python-bot@users.noreply.github.com branch: ${{ inputs.docs-branch }} folder: artifacts/docs/ target-folder: docs/ commit-message: "Deploy ${{ (inputs.is-release && 'release') || 'latest' }} docs: ${{ needs.build.outputs.docs-github-ref }}" clean: false # Rebase onto concurrent PR-preview or coverage deployments instead of # force-pushing, which the gh-pages ruleset rejects. force: false