[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,66 @@ jobs:
           fi
           mv ${COMPONENT}/docs/build/html/* artifacts/docs/${TARGET}
 
-      # TODO: Consider removing this step?
-      - name: Upload doc artifacts
+      - name: Write rendered docs file list
+        if: ${{ !inputs.is-release && github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
+        run: |
+          find "${GITHUB_WORKSPACE}/artifacts/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
+        if: ${{ !inputs.is-release && github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
+        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
+        if: ${{ !inputs.is-release && github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
+        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.
+          # TODO: Remove this exclusion after cybind stops emitting those problematic anchors.
+          # 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() && !inputs.is-release && github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') && 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 }}
+
+      - name: Upload docs GitHub Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
         with:
           path: artifacts/
@@ -265,5 +326,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

.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:
@@ -53,6 +54,18 @@ repos:
           - stubgen-pyx==0.2.6
           - Cython==3.2.4
 
+  # 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
 ^^^^^^^^^^^^^
 

cuda_bindings/docs/source/release/11.8.0-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.8.0 Release notes
@@ -16,7 +16,7 @@ Highlights
 Source Builds
 ^^^^^^^^^^^^^
 
-CUDA Python source builds now parse CUDA headers located in $CUDA_HOME directory, enabling/disabling types and APIs if defined. Therefore this removes the need for CTK headers to have all types defined. By allowing minor variations, previous `11.7.1 mobile platform workaround <https://nvidia.github.io/cuda-python/release/11.7.1-notes.html#source-builds>`_ is no longer needed.
+CUDA Python source builds now parse CUDA headers located in $CUDA_HOME directory, enabling/disabling types and APIs if defined. Therefore this removes the need for CTK headers to have all types defined. By allowing minor variations, previous :ref:`11.7.1 mobile platform workaround <cuda-bindings-11-7-1-source-builds>` is no longer needed.
 
 It's still required that source builds use the latest CTK headers (i.e. “$CUDA_HOME/include” has latest CTK headers).
 

cuda_bindings/docs/source/release/12.9.6-notes.rst

@@ -31,7 +31,7 @@ Bugfixes
 
 * Fixed an issue where the ``CU_POINTER_ATTRIBUTE_DEVICE_ORDINAL`` attribute was
   retrieved as an unsigned int, rather than a signed int.
-  (`PR #1336 <https://github.com/NVIDIA/cuda-python/pull/1336>`_)
+  (`PR #1451 <https://github.com/NVIDIA/cuda-python/pull/1451>`_)
 * Fixed a use-after-free in ``_HelperInputVoidPtr`` properties when backed by
   Python buffer objects.
   (`PR #1629 <https://github.com/NVIDIA/cuda-python/pull/1629>`_)

cuda_bindings/docs/source/release/13.1.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
 
 .. module:: cuda.bindings
@@ -12,7 +12,7 @@ Highlights
 ----------
 
 * Add missing driver & runtime bindings for functions new in CTK 13.1.0
-  (`PR #1321 <https://github.com/NVIDIA/cuda-python/pull/1321>`_)
+  (`PR #1337 <https://github.com/NVIDIA/cuda-python/pull/1337>`_)
 
 Experimental
 ------------

cuda_bindings/docs/source/release/13.2.0-notes.rst

@@ -39,7 +39,7 @@ Bugfixes
 
 * Fixed an issue where the ``CU_POINTER_ATTRIBUTE_DEVICE_ORDINAL`` attribute was
   retrieved as an unsigned int, rather than a signed int.
-  (`PR #1336 <https://github.com/NVIDIA/cuda-python/pull/1336>`_)
+  (`PR #1451 <https://github.com/NVIDIA/cuda-python/pull/1451>`_)
 * Fixed ABI incompatibility bugs in cuFILE bindings introduced in v13.1.0.
   (`PR #1468 <https://github.com/NVIDIA/cuda-python/pull/1468>`_)
 * Fixed a use-after-free in ``_HelperInputVoidPtr`` properties when backed by

cuda_bindings/docs/source/support.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
 
 .. _support:
@@ -38,7 +38,7 @@ The NVIDIA CUDA Python team reserves rights to amend the above support policy. A
 however, will be announced to the users in advance.
 
 
-.. _CUDA minor version compatibility: https://docs.nvidia.com/deploy/cuda-compatibility/#minor-version-compatibility
+.. _CUDA minor version compatibility: https://docs.nvidia.com/deploy/cuda-compatibility/minor-version-compatibility.html
 .. _CPython EOL schedule: https://devguide.python.org/versions/
 .. _built-in modules that are known to be thread-unsafe: https://github.com/python/cpython/issues/116738
 .. _free-threaded interpreter: https://docs.python.org/3/howto/free-threading-python.html

cuda_core/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: Apache-2.0
 
 set -ex
@@ -30,8 +30,11 @@ fi
 
 # build the docs. Allow callers to override SPHINXOPTS for serial/debug runs.
 if [[ -z "${SPHINXOPTS:-}" ]]; then
-    SPHINXOPTS="-W --keep-going -j 4 -d build/.doctrees"
+    HTML_SPHINXOPTS="-W --keep-going -j 4 -d build/.doctrees"
+else
+    HTML_SPHINXOPTS="${SPHINXOPTS}"
 fi
+SPHINXOPTS="${HTML_SPHINXOPTS}"
 make html
 
 # to support version dropdown menu