nvmath-python/.github/workflows/build-docs.yml at ci · NVIDIA/nvmath-python · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0

name: "CI: Build and update docs"

on:
  workflow_call:
    inputs:
      is-release:
        description: "Are we building release docs?"
        required: false
        default: false
        type: boolean
  workflow_dispatch:
    inputs:
      is-release:
        description: "Are we building release docs?"
        required: false
        default: false
        type: boolean

defaults:
  run:
    shell: bash --noprofile --norc -xeuo pipefail {0}

jobs:
  build:
    name: Build docs
    if: ${{ github.repository_owner == 'NVIDIA' && !cancelled() }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout ${{ github.event.repository.name }}
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          fetch-depth: 0

      # pandoc for nbsphinx; OpenMPI for the mpi4py wheel's runtime/build link.
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends pandoc libopenmpi-dev openmpi-bin

      # 3.12 matches build-wheel.yml and the [dependency-groups].docs resolver target.
      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
          cache: pip

      # Build isolation pulls cuda-toolkit[cudart,nvcc] from PyPI for nvcc;
      # the [cu13] extra pulls nvidia-cublas-cu13 etc. wheels for runtime imports.
      # No system CUDA install is required.
      - name: Install nvmath-python and docs deps
        run: |
          pip install --upgrade 'pip>=25.1'
          pip install -v ".[cu13]" --group pyproject.toml:docs

      # Surface autodoc import failures here, where they're easy to spot in logs.
      # nvmath.distributed needs nvshmem/nccl which we deliberately don't install,
      # so its failure is downgraded to a warning.
      - name: Smoke-test imports
        run: |
          python -c "import nvmath; print('nvmath', nvmath.__version__)"
          python -c "import nvmath.bindings, nvmath.fft, nvmath.linalg, nvmath.sparse, nvmath.tensor"
          python -c "import nvmath.distributed" || echo "::warning::nvmath.distributed import failed (expected without nvshmem/nccl)"

      # Sets PR_NUMBER (and BUILD_PREVIEW/BUILD_LATEST) in $GITHUB_ENV.
      - name: Get PR number
        if: ${{ !inputs.is-release }}
        uses: ./.github/actions/get_pr_number

      # Override the Makefile's -W default until we know the warning baseline is zero.
      - name: Build docs
        run: |
          mkdir -p docs/_build/empty
          make -C docs html SPHINXOPTS="-j auto"
          ls -la docs/_build/html

      # On release tags, drop the moving "latest/" pointer + top-level index/objects
      # so the deploy only adds the new <ver>/ folder.
      - name: Strip latest/ for release deploy
        if: ${{ inputs.is-release }}
        run: |
          rm -rf docs/_build/html/latest
          rm -f  docs/_build/html/index.html docs/_build/html/objects.inv

      # On PR refs, deploy preview to docs/pr-preview/pr-<N>/.
      # On main/release/*, the doc_preview action expects an empty source folder
      # so its cleanup branch removes (rather than replaces) the PR preview.
      - name: Deploy or clean up doc preview
        if: ${{ !inputs.is-release }}
        uses: ./.github/actions/doc_preview
        with:
          source-folder: ${{ (github.ref_name != 'main' && !startsWith(github.ref_name, 'release/'))
                              && 'docs/_build/html' || 'docs/_build/empty' }}
          pr-number: ${{ env.PR_NUMBER }}

      - name: Deploy to GitHub Pages
        if: ${{ github.ref_name == 'main' || inputs.is-release }}
        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f  # v4.8.0
        with:
          git-config-name: nvmath-python-bot
          git-config-email: nvmath-python-bot@users.noreply.github.com
          folder: docs/_build/html/
          target-folder: docs/
          commit-message: "Deploy ${{ (inputs.is-release && 'release') || 'latest' }} docs: ${{ github.sha }}"
          clean: false