[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,15 +91,18 @@ 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
           else
             FILE_HASH="${{ github.sha }}"
-            COMMIT_HASH="${{ github.sha }}"
+            DOCS_GITHUB_REF="${{ 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_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
@@ -242,8 +245,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/
@@ -265,5 +278,5 @@ jobs:
           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 }}"
+          commit-message: "Deploy ${{ (inputs.is-release && 'release') || 'latest' }} docs: ${{ env.CUDA_PYTHON_DOCS_GITHUB_REF }}"
           clean: false

.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,18 @@ repos:
         language: system
         files: '^.*/docs/source/.*\.md$'
 
+  # Link checking for authored documentation files
+  - repo: https://github.com/lycheeverse/lychee
+    rev: 2bba271688c1abb1503097a064e6c3bc1d1b6a9b  # frozen: lychee-v0.24.2
+    hooks:
+      - id: lychee
+        args:
+          - --cache
+          - --max-concurrency=4
+          - --max-retries=3
+          - --no-progress
+        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/runtime.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright (c) 2021-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-FileCopyrightText: Copyright (c) 2021-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 .. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 -------
@@ -299,7 +299,7 @@ Data types used by CUDA Runtime
     .. autoattribute:: cuda.bindings.runtime.cudaError_t.cudaErrorIncompatibleDriverContext
 
 
-        This indicates that the current context is not compatible with this the CUDA Runtime. This can only occur if you are using CUDA Runtime/Driver interoperability and have created an existing Driver context using the driver API. The Driver context may be incompatible either because the Driver context was created using an older version of the API, because the Runtime API call expects a primary driver context and the Driver context is not primary, or because the Driver context has been destroyed. Please see :py:obj:`~.Interactions`with the CUDA Driver API" for more information.
+        This indicates that the current context is not compatible with this the CUDA Runtime. This can only occur if you are using CUDA Runtime/Driver interoperability and have created an existing Driver context using the driver API. The Driver context may be incompatible either because the Driver context was created using an older version of the API, because the Runtime API call expects a primary driver context and the Driver context is not primary, or because the Driver context has been destroyed. Please see `Interactions with the CUDA Driver API`_ for more information.
 
 
     .. autoattribute:: cuda.bindings.runtime.cudaError_t.cudaErrorMissingConfiguration

cuda_bindings/docs/source/motivation.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
 
 Motivation
@@ -31,7 +31,7 @@ you get the best of both worlds: rapid iterative development with Python and the
 speed of a compiled language targeting both CPUs and NVIDIA GPUs.
 
 `CuPy <https://cupy.dev/>`_ is a
-`NumPy <https://numpy.org/>`_/`SciPy <https://www.scipy.org/>`_ compatible Array
+`NumPy <https://numpy.org/>`_/`SciPy <https://scipy.org/>`_ compatible Array
 library, from `Preferred Networks <https://www.preferred.jp/en/>`_, for
 GPU-accelerated computing with Python. CUDA Python simplifies the CuPy build
 and allows for a faster and smaller memory footprint when importing the CuPy

cuda_bindings/docs/source/overview.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
 
 Overview
@@ -38,8 +38,8 @@ The first thing to do is import the `Driver
 API <https://docs.nvidia.com/cuda/cuda-driver-api/index.html>`_ and
 `NVRTC <https://docs.nvidia.com/cuda/nvrtc/index.html>`_ modules from the ``cuda.bindings``
 package. Next, we consider how to store host data and pass it to the device. Different
-approaches can be used to accomplish this and are described in `Preparing kernel
-arguments <https://nvidia.github.io/cuda-python/cuda-bindings/latest/overview.html#preparing-kernel-arguments>`_.
+approaches can be used to accomplish this and are described in
+:ref:`Preparing kernel arguments <preparing-kernel-arguments>`.
 In this example, we will use NumPy to store host data and pass it to the device, so let's
 import this dependency as well.
 
@@ -308,6 +308,8 @@ maximize performance ({numref}``Figure 1``).
 
    Screenshot of Nsight Compute CLI output of ``cuda.bindings`` example.
 
+.. _preparing-kernel-arguments:
+
 Preparing kernel arguments
 --------------------------
 

cuda_bindings/docs/source/release/11.7.1-notes.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
 
 CUDA Python 11.7.1 Release notes
@@ -14,6 +14,8 @@ Highlights
 Limitations
 -----------
 
+.. _cuda-bindings-11-7-1-source-builds:
+
 Source builds
 ^^^^^^^^^^^^^