build-docs.yml

# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0

name: "CI: Build and update docs"

on:
  workflow_call:
    inputs:
      build-ctk-ver:
        type: string
        required: true
      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

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
    defaults:
      run:
        shell: bash -el {0}
    steps:
      - name: validate build-ctk
        run: |
          if [ ! "${{ inputs.build-ctk-ver }}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]; then
            echo "error: `build-ctk-ver` ${{ inputs.build-ctk-ver }} version does not match MAJOR.MINOR.MICRO" >&2
            exit 1
          fi
      - name: Checkout ${{ github.event.repository.name }}
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          fetch-depth: 0
          ref: ${{ inputs.git-tag }}

      # TODO: This workflow runs on GH-hosted runner and cannot use the proxy cache

      - name: Set up miniforge
        uses: conda-incubator/setup-miniconda@fc2d68f6413eb2d87b895e92f8584b5b94a10167  # v3.3.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: ${{ inputs.build-ctk-ver }}

      - name: Set environment variables
        run: |
          PYTHON_VERSION_FORMATTED="312"  # see above
          REPO_DIR=$(pwd)

          if [[ ${{ inputs.is-release }} == "true" ]]; then
            FILE_HASH="*"
            COMMIT_HASH="${{ inputs.git-tag }}"
          else
            FILE_HASH="${{ github.sha }}"
            COMMIT_HASH="${{ github.sha }}"
          fi

          # make outputs from the previous job as env vars
          CUDA_CORE_ARTIFACT_BASENAME="cuda-core-python${PYTHON_VERSION_FORMATTED}-linux-64"
          echo "COMMIT_HASH=${COMMIT_HASH}" >> $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${{ inputs.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/dist")" >> $GITHUB_ENV

      - name: Download cuda-python build artifacts
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
        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: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
        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: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
        with:
          name: ${{ env.CUDA_BINDINGS_ARTIFACT_NAME }}
          path: ${{ env.CUDA_BINDINGS_ARTIFACTS_DIR }}

      - name: Download cuda.bindings build artifacts
        if: ${{ inputs.is-release }}
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
        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: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
        with:
          name: ${{ env.CUDA_CORE_ARTIFACT_NAME }}
          path: ${{ env.CUDA_CORE_ARTIFACTS_DIR }}

      - name: Download cuda.core build artifacts
        if: ${{ inputs.is-release }}
        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
        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

          pip install cuda_python*.whl

      # This step sets the PR_NUMBER/BUILD_LATEST/BUILD_PREVIEW env vars.
      - name: Get PR number
        if: ${{ !inputs.is-release }}
        uses: ./.github/actions/get_pr_number

      - name: Set up artifact directories
        run: |
          mkdir -p artifacts/docs
          # create an empty folder for removal use
          mkdir -p artifacts/empty_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
          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 '-' '_')
          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
          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}

      # TODO: Consider removing this step?
      - name: Upload doc artifacts
        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b  # v4.0.0
        with:
          path: artifacts/
          retention-days: 3

      - name: Deploy or clean up doc preview
        if: ${{ !inputs.is-release }}
        uses: ./.github/actions/doc_preview
        with:
          source-folder: ${{ (github.ref_name != 'main' && 'artifacts/docs') ||
                              'artifacts/empty_docs' }}
          pr-number: ${{ env.PR_NUMBER }}

      - name: Deploy doc update
        if: ${{ github.ref_name == 'main' || inputs.is-release }}
        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f  # v4.8.0
        with:
          git-config-name: cuda-python-bot
          git-config-email: cuda-python-bot@users.noreply.github.com
          folder: artifacts/docs/
          target-folder: docs/
          commit-message: "Deploy ${{ (inputs.is-release && 'release') || 'latest' }} docs: ${{ env.COMMIT_HASH }}"
          clean: false