[codex] Add lychee docs link checks and stable source links

.github/workflows/build-docs.yml

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -91,14 +91,20 @@ jobs:
 
           if [[ ${{ inputs.is-release }} == "true" ]]; then
             FILE_HASH="*"
-            COMMIT_HASH="${{ inputs.git-tag }}"
+            DOCS_GITHUB_REF="${{ inputs.git-tag }}"
+            if [[ -z "${DOCS_GITHUB_REF}" ]]; then
+              DOCS_GITHUB_REF="${GITHUB_REF_NAME}"
+            fi
+            COMMIT_HASH="${DOCS_GITHUB_REF}"
           else
             FILE_HASH="${{ github.sha }}"
-            COMMIT_HASH="${{ github.sha }}"
+            DOCS_GITHUB_REF="${{ github.sha }}"
+            COMMIT_HASH="${DOCS_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 "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
@@ -242,8 +248,18 @@ jobs:
           fi
           mv ${COMPONENT}/docs/build/html/* artifacts/docs/${TARGET}
 
-      # TODO: Consider removing this step?
-      - name: Upload doc artifacts
+      - name: Upload rendered docs for link checking
+        if: ${{ !inputs.is-release && github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: docs-rendered-html
+          path: artifacts/docs/
+          if-no-files-found: error
+          retention-days: 3
+
+      # This is the GitHub Pages artifact format; the link checker needs a
+      # normal workflow artifact with the rendered HTML tree above.
+      - name: Upload docs GitHub Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
         with:
           path: artifacts/

.github/workflows/check-doc-links.yml

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: "CI: Check rendered docs links"
+
+on:
+  workflow_call:
+    inputs:
+      docs-artifact:
+        description: "Artifact containing the rendered docs HTML tree"
+        required: false
+        default: docs-rendered-html
+        type: string
+
+jobs:
+  check:
+    name: Check rendered docs links
+    if: ${{ github.repository_owner == 'nvidia' && startsWith(github.ref_name, 'pull-request/') }}
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: read
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - name: Extract PR number
+        run: |
+          PR_NUMBER="${GITHUB_REF_NAME#pull-request/}"
+          if [[ ! "${PR_NUMBER}" =~ ^[0-9]+$ ]]; then
+            echo "error: cannot extract PR number from ref ${GITHUB_REF_NAME}" >&2
+            exit 1
+          fi
+          echo "PR_NUMBER=${PR_NUMBER}" >> "${GITHUB_ENV}"
+
+      - name: Download rendered docs
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: ${{ inputs.docs-artifact }}
+          path: rendered-docs
+
+      - name: Write rendered docs file list
+        run: |
+          find "${GITHUB_WORKSPACE}/rendered-docs" -type f -name '*.html' ! -path '*/_static/*' \
+            | LC_ALL=C sort > lychee-rendered-html-files.txt
+          if [[ ! -s lychee-rendered-html-files.txt ]]; then
+            echo "error: no rendered HTML pages found for lychee" >&2
+            exit 1
+          fi
+          wc -l lychee-rendered-html-files.txt
+
+      - name: Restore lychee cache
+        id: restore-lychee-cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830  # v4
+        with:
+          path: .lycheecache
+          key: docs-rendered-lychee-${{ env.PR_NUMBER }}-${{ github.sha }}
+          restore-keys: |
+            docs-rendered-lychee-${{ env.PR_NUMBER }}-
+
+      - name: Check rendered docs links
+        uses: lycheeverse/lychee-action@6da1d14f3a43098a294b7696d93d938aa8d20fc0  # unreleased: supports v0.24.x archive layout
+        with:
+          # PR-preview canonical URLs are checked by the preview deployment workflow.
+          # The cuda-bindings #id links are docutils "problematic" anchors from generated API docs.
+          # Preferred Networks rejects hosted-runner GETs, but the URL is browser reachable.
+          args: >-
+            --files-from ${{ github.workspace }}/lychee-rendered-html-files.txt
+            --include-fragments=full
+            --cache
+            --max-cache-age 1d
+            --max-concurrency 16
+            --host-concurrency 2
+            --host-request-interval 250ms
+            --max-retries 3
+            --retry-wait-time 5
+            --timeout 30
+            --no-progress
+            --exclude '^https://nvidia\.github\.io/cuda-python/pr-preview/pr-[0-9]+/'
+            --exclude '^file://.*/cuda-bindings/latest/module/(driver|runtime)\.html#id[0-9]+$'
+            --exclude '^https://www\.preferred\.jp/en/?$'
+          fail: true
+          failIfEmpty: true
+          format: markdown
+          jobSummary: false
+          lycheeVersion: v0.24.2
+          output: lychee-rendered-html.md
+          token: ${{ github.token }}
+
+      - name: Save lychee cache
+        if: ${{ always() && steps.restore-lychee-cache.outputs.cache-hit != 'true' && steps.restore-lychee-cache.outputs.cache-primary-key != '' }}
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830  # v4
+        with:
+          path: .lycheecache
+          key: ${{ steps.restore-lychee-cache.outputs.cache-primary-key }}

.github/workflows/ci.yml

@@ -412,6 +412,18 @@ jobs:
     with:
       is-release: ${{ github.ref_type == 'tag' }}
 
+  doc-linkcheck:
+    name: Docs link check
+    if: ${{ github.repository_owner == 'nvidia' && startsWith(github.ref_name, 'pull-request/') && needs.doc.result == 'success' }}
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: read
+    needs:
+      - doc
+    secrets: inherit
+    uses: ./.github/workflows/check-doc-links.yml
+
   checks:
     name: Check job status
     if: always()
@@ -425,6 +437,7 @@ jobs:
       - test-linux-aarch64
       - test-windows
       - doc
+      - doc-linkcheck
     steps:
       - name: Exit
         run: |
@@ -460,6 +473,9 @@ jobs:
           if ${{ needs.doc.result == 'cancelled' || needs.doc.result == 'failure' }}; then
             exit 1
           fi
+          if ${{ needs.doc-linkcheck.result == 'cancelled' || needs.doc-linkcheck.result == 'failure' }}; then
+            exit 1
+          fi
           if ${{ needs.test-sdist-linux.result == 'cancelled' ||
                  needs.test-sdist-linux.result == 'failure' ||
                  needs.test-sdist-windows.result == 'cancelled' ||

.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 
 # CUDA Python specific
 .cache/
+.lycheecache
 .pytest_cache/
 .benchmarks/
 *.cpp

.pre-commit-config.yaml

@@ -9,6 +9,7 @@ ci:
     autoupdate_branch: ''
     autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate'
     autoupdate_schedule: quarterly
+    skip: [lychee]
     submodules: false
 
 # Please update the rev: SHAs below with this command:
@@ -42,6 +43,21 @@ repos:
         language: system
         files: '^.*/docs/source/.*\.md$'
 
+  # Link checking for authored documentation files
+  - repo: https://github.com/lycheeverse/lychee
+    rev: lychee-v0.24.2
+    hooks:
+      - id: lychee
+        args:
+          - LYCHEE_VERSION=0.24.2
+          - --cache
+          - --max-concurrency=4
+          - --max-retries=3
+          - --no-progress
+          - --exclude
+          - '^https://github\.com/NVIDIA/cuda-python/(blob|tree)/$'
+        files: '\.(md|rst)$'
+
   # Standard hooks
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: "3e8a8703264a2f4a69428a0aa4dcb512790b2c8c"  # frozen: v6.0.0

cuda_bindings/docs/build_docs.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 set -ex
@@ -30,7 +30,12 @@ if [[ "${LATEST_ONLY}" == "1" && -z "${BUILD_PREVIEW:-}" && -z "${BUILD_LATEST:-
 fi
 
 # build the docs (in parallel)
-SPHINXOPTS="-j 4 -d build/.doctrees" make html
+if [[ -z "${SPHINXOPTS:-}" ]]; then
+    HTML_SPHINXOPTS="-j 4 -d build/.doctrees"
+else
+    HTML_SPHINXOPTS="${SPHINXOPTS}"
+fi
+SPHINXOPTS="${HTML_SPHINXOPTS}" make html
 
 # for debugging/developing (conf.py), please comment out the above line and
 # use the line below instead, as we must build in serial to avoid getting

cuda_bindings/docs/source/conduct.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 .. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 Code of Conduct
@@ -85,7 +85,7 @@ Attribution
 -----------
 
 This Code of Conduct is adapted from the `Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct/
 
 For answers to common questions about this code of conduct, see
 https://www.contributor-covenant.org/faq

cuda_bindings/docs/source/conf.py

@@ -27,6 +27,8 @@
 
 
 def _github_examples_ref():
+    if ref := os.environ.get("CUDA_PYTHON_DOCS_GITHUB_REF"):
+        return ref
     if int(os.environ.get("BUILD_PREVIEW", 0)) or int(os.environ.get("BUILD_LATEST", 0)):
         return "main"
     return f"v{release}"
@@ -35,6 +37,15 @@ def _github_examples_ref():
 GITHUB_EXAMPLES_REF = _github_examples_ref()
 
 
+def _html_baseurl():
+    docs_domain = os.environ.get("CUDA_PYTHON_DOCS_DOMAIN", "https://nvidia.github.io/cuda-python")
+    if int(os.environ.get("BUILD_PREVIEW", 0)):
+        return f"{docs_domain}/pr-preview/pr-{os.environ['PR_NUMBER']}/cuda-bindings/latest/"
+    if int(os.environ.get("BUILD_LATEST", 0)):
+        return f"{docs_domain}/cuda-bindings/latest/"
+    return f"{docs_domain}/cuda-bindings/{release}/"
+
+
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -74,7 +85,7 @@ def _github_examples_ref():
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_baseurl = "docs"
+html_baseurl = _html_baseurl()
 html_theme = "nvidia_sphinx_theme"
 html_theme_options = {
     "switcher": {
@@ -130,12 +141,8 @@ def _github_examples_ref():
 
 
 def rewrite_source(app, docname, source):
-    text = source[0]
-
     if docname.startswith("release/"):
-        text = text.replace(".. module:: cuda.bindings\n\n", "", 1)
-
-    source[0] = text
+        source[0] = source[0].replace(".. module:: cuda.bindings\n\n", "", 1)
 
 
 suppress_warnings = [

cuda_bindings/docs/source/install.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 .. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 Installation
@@ -99,7 +99,7 @@ Source builds require that the provided CUDA headers are of the same major.minor
 
    $ export CUDA_PATH=/usr/local/cuda
 
-See `Environment Variables <environment_variables.rst>`_ for a description of other build-time environment variables.
+See :doc:`Environment Variables <environment_variables>` for a description of other build-time environment variables.
 
 .. note::
 

cuda_bindings/docs/source/module/driver.rst

@@ -406,25 +406,25 @@ Data types used by CUDA driver
     .. autoattribute:: cuda.bindings.driver.CUstreamWaitValue_flags.CU_STREAM_WAIT_VALUE_GEQ
 
 
-        Wait until (int32_t)(*addr - value) >= 0 (or int64_t for 64 bit values). Note this is a cyclic comparison which ignores wraparound. (Default behavior.)
+        Wait until (int32_t)(\*addr - value) >= 0 (or int64_t for 64 bit values). Note this is a cyclic comparison which ignores wraparound. (Default behavior.)
 
 
     .. autoattribute:: cuda.bindings.driver.CUstreamWaitValue_flags.CU_STREAM_WAIT_VALUE_EQ
 
 
-        Wait until *addr == value.
+        Wait until \*addr == value.
 
 
     .. autoattribute:: cuda.bindings.driver.CUstreamWaitValue_flags.CU_STREAM_WAIT_VALUE_AND
 
 
-        Wait until (*addr & value) != 0.
+        Wait until (\*addr & value) != 0.
 
 
     .. autoattribute:: cuda.bindings.driver.CUstreamWaitValue_flags.CU_STREAM_WAIT_VALUE_NOR
 
 
-        Wait until ~(*addr | value) != 0. Support for this operation can be queried with :py:obj:`~.cuDeviceGetAttribute()` and :py:obj:`~.CU_DEVICE_ATTRIBUTE_CAN_USE_STREAM_WAIT_VALUE_NOR`.
+        Wait until ~(\*addr | value) != 0. Support for this operation can be queried with :py:obj:`~.cuDeviceGetAttribute()` and :py:obj:`~.CU_DEVICE_ATTRIBUTE_CAN_USE_STREAM_WAIT_VALUE_NOR`.
 
 
     .. autoattribute:: cuda.bindings.driver.CUstreamWaitValue_flags.CU_STREAM_WAIT_VALUE_FLUSH
@@ -506,19 +506,19 @@ Data types used by CUDA driver
     .. autoattribute:: cuda.bindings.driver.CUstreamAtomicReductionOpType.CU_STREAM_ATOMIC_REDUCTION_OP_OR
 
 
-        Performs an atomic OR: *(address) = *(address) | value
+        Performs an atomic OR: \*(address) = \*(address) | value
 
 
     .. autoattribute:: cuda.bindings.driver.CUstreamAtomicReductionOpType.CU_STREAM_ATOMIC_REDUCTION_OP_AND
 
 
-        Performs an atomic AND: *(address) = *(address) & value
+        Performs an atomic AND: \*(address) = \*(address) & value
 
 
     .. autoattribute:: cuda.bindings.driver.CUstreamAtomicReductionOpType.CU_STREAM_ATOMIC_REDUCTION_OP_ADD
 
 
-        Performs an atomic ADD: *(address) = *(address) + value
+        Performs an atomic ADD: \*(address) = \*(address) + value
 
 .. autoclass:: cuda.bindings.driver.CUstreamAtomicReductionDataType