build-docs.yml

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
        #   - all
      git-tag:
        description: "Target git tag to build docs for"
        required: false
        default: ""
        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() }}
    # WAR: Building the doc currently requires a GPU (NVIDIA/cuda-python#326,327)
    runs-on: linux-amd64-gpu-t4-latest-1-testing
    #runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -el {0}
    steps:
      # WAR: Building the doc currently requires a GPU (NVIDIA/cuda-python#326,327)
      - name: Ensure GPU is working
        run: nvidia-smi

      - name: Checkout ${{ github.event.repository.name }}
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ inputs.git-tag }}

      # TODO: cache conda env to speed up the workflow once conda-incubator/setup-miniconda#267
      # is resolved

      - name: Set up miniforge
        uses: conda-incubator/setup-miniconda@v3
        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)

          # make outputs from the previous job as env vars
          CUDA_CORE_ARTIFACT_BASENAME="cuda-core-python${PYTHON_VERSION_FORMATTED}-linux-64"
          echo "CUDA_CORE_ARTIFACT_BASENAME=${CUDA_CORE_ARTIFACT_BASENAME}" >> $GITHUB_ENV
          echo "CUDA_CORE_ARTIFACT_NAME=${CUDA_CORE_ARTIFACT_BASENAME}-${{ github.sha }}" >> $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}-${{ github.sha }}" >> $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@v4
        with:
          name: cuda-python-wheel
          path: .

      - name: Display structure of downloaded cuda-python artifacts
        run: |
          pwd
          ls -lahR .

      - name: Download cuda.bindings build artifacts
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.CUDA_BINDINGS_ARTIFACT_NAME }}
          path: ${{ env.CUDA_BINDINGS_ARTIFACTS_DIR }}

      - name: Display structure of downloaded cuda.bindings artifacts
        run: |
          pwd
          ls -lahR $CUDA_BINDINGS_ARTIFACTS_DIR

      - name: Download cuda.core build artifacts
        uses: actions/download-artifact@v4
        with:
          name: ${{ env.CUDA_CORE_ARTIFACT_NAME }}
          path: ${{ env.CUDA_CORE_ARTIFACTS_DIR }}

      - name: Display structure of downloaded cuda.core build artifacts
        run: |
          pwd
          ls -lahR $CUDA_CORE_ARTIFACTS_DIR

      - name: Install all packages
        run: |
          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' }}
        env:
          DOC_ACTION: ${{ (inputs.is-release && '') || 'latest-only' }}
        run: |
          pushd cuda_python/docs/
          ./build_all_docs.sh $DOC_ACTION
          if [[ -z "$DOC_ACTION" ]]; then
            # 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' }}
        env:
          DOC_ACTION: ${{ (inputs.is-release && '') || 'latest-only' }}
        run: |
          COMPONENT=$(echo "${{ inputs.component }}" | tr '-' '_')
          pushd ${COMPONENT}/docs/
          ./build_docs.sh $DOC_ACTION
          if [[ -z "$DOC_ACTION" ]]; then
            # At release time, we don't want to update the latest docs
            rm -rf build/html/latest
          fi
          ls -l build
          popd
          mv ${COMPONENT}/docs/build/html/* artifacts/docs/

      # TODO: Consider removing this step?
      - name: Upload doc artifacts
        uses: actions/upload-pages-artifact@v3
        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@v4
        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: ${{ github.sha }}"
          clean: false