diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index e95a50b2a03..45fa53ab1b1 100644 --- a/.github/workflows/build-docs.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 26f13b1d174..e15f36ccc46 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ __pycache__/ # CUDA Python specific .cache/ +.lycheecache .pytest_cache/ .benchmarks/ *.cpp diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 25fb48eca34..40121b6f0fe 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/cuda_bindings/docs/build_docs.sh b/cuda_bindings/docs/build_docs.sh index 15a42b93464..2ab1f086018 100755 --- a/cuda_bindings/docs/build_docs.sh +++ b/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 diff --git a/cuda_bindings/docs/source/conduct.rst b/cuda_bindings/docs/source/conduct.rst index b70d9dd7ce3..26d3f1e59f9 100644 --- a/cuda_bindings/docs/source/conduct.rst +++ b/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 `_, 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 diff --git a/cuda_bindings/docs/source/conf.py b/cuda_bindings/docs/source/conf.py index 69a05d6e52f..64f28ace24d 100644 --- a/cuda_bindings/docs/source/conf.py +++ b/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 = [ diff --git a/cuda_bindings/docs/source/install.rst b/cuda_bindings/docs/source/install.rst index bb5a8585257..ce99255c133 100644 --- a/cuda_bindings/docs/source/install.rst +++ b/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 `_ for a description of other build-time environment variables. +See :doc:`Environment Variables ` for a description of other build-time environment variables. .. note:: diff --git a/cuda_bindings/docs/source/module/runtime.rst b/cuda_bindings/docs/source/module/runtime.rst index 5f7b5177560..29da14b40de 100644 --- a/cuda_bindings/docs/source/module/runtime.rst +++ b/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 diff --git a/cuda_bindings/docs/source/motivation.rst b/cuda_bindings/docs/source/motivation.rst index 433cc166193..16bfd9745af 100644 --- a/cuda_bindings/docs/source/motivation.rst +++ b/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 `_ is a -`NumPy `_/`SciPy `_ compatible Array +`NumPy `_/`SciPy `_ compatible Array library, from `Preferred Networks `_, 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 diff --git a/cuda_bindings/docs/source/overview.rst b/cuda_bindings/docs/source/overview.rst index e0d269cb6b6..8ada38bfd22 100644 --- a/cuda_bindings/docs/source/overview.rst +++ b/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 `_ and `NVRTC `_ 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 `_. +approaches can be used to accomplish this and are described in +:ref:`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 -------------------------- diff --git a/cuda_bindings/docs/source/release/11.7.1-notes.rst b/cuda_bindings/docs/source/release/11.7.1-notes.rst index 0fbea248e36..385cfb6e233 100644 --- a/cuda_bindings/docs/source/release/11.7.1-notes.rst +++ b/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 ^^^^^^^^^^^^^ diff --git a/cuda_bindings/docs/source/release/11.8.0-notes.rst b/cuda_bindings/docs/source/release/11.8.0-notes.rst index e24022142df..68e40bc325d 100644 --- a/cuda_bindings/docs/source/release/11.8.0-notes.rst +++ b/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 `_ 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 ` 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). diff --git a/cuda_bindings/docs/source/release/12.9.6-notes.rst b/cuda_bindings/docs/source/release/12.9.6-notes.rst index dd508ff1478..d24671700bf 100644 --- a/cuda_bindings/docs/source/release/12.9.6-notes.rst +++ b/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 `_) + (`PR #1451 `_) * Fixed a use-after-free in ``_HelperInputVoidPtr`` properties when backed by Python buffer objects. (`PR #1629 `_) diff --git a/cuda_bindings/docs/source/release/13.1.1-notes.rst b/cuda_bindings/docs/source/release/13.1.1-notes.rst index 37353cbe145..4725fe570c6 100644 --- a/cuda_bindings/docs/source/release/13.1.1-notes.rst +++ b/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 `_) + (`PR #1337 `_) Experimental ------------ diff --git a/cuda_bindings/docs/source/release/13.2.0-notes.rst b/cuda_bindings/docs/source/release/13.2.0-notes.rst index 4ea580c9c53..71d2e13e562 100644 --- a/cuda_bindings/docs/source/release/13.2.0-notes.rst +++ b/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 `_) + (`PR #1451 `_) * Fixed ABI incompatibility bugs in cuFILE bindings introduced in v13.1.0. (`PR #1468 `_) * Fixed a use-after-free in ``_HelperInputVoidPtr`` properties when backed by diff --git a/cuda_bindings/docs/source/support.rst b/cuda_bindings/docs/source/support.rst index 4439d963c0e..0ed4d023efa 100644 --- a/cuda_bindings/docs/source/support.rst +++ b/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 diff --git a/cuda_core/docs/build_docs.sh b/cuda_core/docs/build_docs.sh index 78038438bcc..28ae6dd07fd 100755 --- a/cuda_core/docs/build_docs.sh +++ b/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 diff --git a/cuda_core/docs/source/conduct.rst b/cuda_core/docs/source/conduct.rst index 1c00f5c3430..d6df40945a1 100644 --- a/cuda_core/docs/source/conduct.rst +++ b/cuda_core/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: Apache-2.0 Code of Conduct @@ -85,7 +85,7 @@ Attribution ----------- This Code of Conduct is adapted from the `Contributor Covenant `_, 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 diff --git a/cuda_core/docs/source/conf.py b/cuda_core/docs/source/conf.py index 14d93297937..451eb8b4453 100644 --- a/cuda_core/docs/source/conf.py +++ b/cuda_core/docs/source/conf.py @@ -28,6 +28,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"cuda-core-v{release}" @@ -36,6 +38,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-core/latest/" + if int(os.environ.get("BUILD_LATEST", 0)): + return f"{docs_domain}/cuda-core/latest/" + return f"{docs_domain}/cuda-core/{release}/" + + # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -44,6 +55,7 @@ def _github_examples_ref(): extensions = [ "sphinx.ext.autodoc", "sphinx.ext.autosummary", + "sphinx.ext.extlinks", "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.extlinks", @@ -73,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": { diff --git a/cuda_core/docs/source/examples.rst b/cuda_core/docs/source/examples.rst index e3b2ef8f3f5..cf13961c6dc 100644 --- a/cuda_core/docs/source/examples.rst +++ b/cuda_core/docs/source/examples.rst @@ -12,48 +12,48 @@ workflow. Compilation and kernel launch ----------------------------- -- :cuda-core-example:`vector_add.py` +- :cuda-core-example:`vector_add.py ` compiles and launches a simple vector-add kernel with CuPy arrays. -- :cuda-core-example:`saxpy.py` +- :cuda-core-example:`saxpy.py ` JIT-compiles a templated SAXPY kernel and launches both float and double instantiations. -- :cuda-core-example:`pytorch_example.py` +- :cuda-core-example:`pytorch_example.py ` launches a CUDA kernel with PyTorch tensors and a wrapped PyTorch stream. Multi-device and advanced launch configuration ---------------------------------------------- -- :cuda-core-example:`simple_multi_gpu_example.py` +- :cuda-core-example:`simple_multi_gpu_example.py ` compiles and launches kernels across multiple GPUs. -- :cuda-core-example:`thread_block_cluster.py` +- :cuda-core-example:`thread_block_cluster.py ` demonstrates thread block cluster launch configuration on Hopper-class GPUs. -- :cuda-core-example:`tma_tensor_map.py` +- :cuda-core-example:`tma_tensor_map.py ` demonstrates Tensor Memory Accelerator descriptors and TMA-based bulk copies. Linking and graphs ------------------ -- :cuda-core-example:`jit_lto_fractal.py` +- :cuda-core-example:`jit_lto_fractal.py ` uses JIT link-time optimization to link user-provided device code into a fractal workflow at runtime. -- :cuda-core-example:`cuda_graphs.py` +- :cuda-core-example:`cuda_graphs.py ` captures and replays a multi-kernel CUDA graph to reduce launch overhead. Interoperability and memory access ---------------------------------- -- :cuda-core-example:`memory_ops.py` +- :cuda-core-example:`memory_ops.py ` covers memory resources, pinned memory, device transfers, and DLPack interop. -- :cuda-core-example:`strided_memory_view_cpu.py` +- :cuda-core-example:`strided_memory_view_cpu.py ` uses ``StridedMemoryView`` with JIT-compiled CPU code via ``cffi``. -- :cuda-core-example:`strided_memory_view_gpu.py` +- :cuda-core-example:`strided_memory_view_gpu.py ` uses ``StridedMemoryView`` with JIT-compiled GPU code and foreign GPU buffers. -- :cuda-core-example:`gl_interop_plasma.py` +- :cuda-core-example:`gl_interop_plasma.py ` renders a CUDA-generated plasma effect through OpenGL interop without CPU copies. System inspection ----------------- -- :cuda-core-example:`show_device_properties.py` +- :cuda-core-example:`show_device_properties.py ` prints a detailed report of the CUDA devices available on the system. diff --git a/cuda_core/docs/source/getting-started.rst b/cuda_core/docs/source/getting-started.rst index fb2f0b22fcf..e03ce23782f 100644 --- a/cuda_core/docs/source/getting-started.rst +++ b/cuda_core/docs/source/getting-started.rst @@ -32,7 +32,7 @@ Example: Compiling and Launching a CUDA kernel ---------------------------------------------- To get a taste for ``cuda.core``, let's walk through a simple example that compiles and launches a vector addition kernel. -You can find the complete example in :cuda-core-example:`vector_add.py` +You can find the complete example in :cuda-core-example:`vector_add.py ` and browse the :doc:`examples page ` for the rest of the shipped workflows. @@ -80,7 +80,7 @@ Note the use of the ``name_expressions`` parameter to the :meth:`Program.compile Next, we retrieve the compiled kernel from the CUBIN and prepare the arguments and kernel configuration. We're using `CuPy `_ arrays as inputs for this example, but you can use PyTorch tensors too (see -:cuda-core-example:`pytorch_example.py` +:cuda-core-example:`pytorch_example.py ` and the :doc:`examples page `). .. code-block:: python diff --git a/cuda_core/docs/source/interoperability.rst b/cuda_core/docs/source/interoperability.rst index 4aa155ce5f9..87347eb9d25 100644 --- a/cuda_core/docs/source/interoperability.rst +++ b/cuda_core/docs/source/interoperability.rst @@ -70,11 +70,11 @@ a few iterations to ensure correctness. for extracting the metadata (such as pointer address, shape, strides, and dtype) from any Python objects supporting either CAI or DLPack and returning a :class:`~utils.StridedMemoryView` object. See the -:cuda-core-example:`strided_memory_view_constructors.py` +:cuda-core-example:`strided_memory_view_constructors.py ` example for the explicit constructors, or -:cuda-core-example:`strided_memory_view_cpu.py` +:cuda-core-example:`strided_memory_view_cpu.py ` and -:cuda-core-example:`strided_memory_view_gpu.py` +:cuda-core-example:`strided_memory_view_gpu.py ` for decorator-based workflows. This provides a *concrete implementation* to both protocols that is **array-library-agnostic**, so that all Python projects can just rely on this without either re-implementing (the consumer-side of) diff --git a/cuda_core/docs/source/release/0.3.1-notes.rst b/cuda_core/docs/source/release/0.3.1-notes.rst index 82138763db2..8360d1b9eb7 100644 --- a/cuda_core/docs/source/release/0.3.1-notes.rst +++ b/cuda_core/docs/source/release/0.3.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: Apache-2.0 .. currentmodule:: cuda.core.experimental @@ -31,8 +31,8 @@ None. New examples ------------ -- Add a `CUDA graph `_ example. -- Add a `memory resource `_ example. +- Add a :cuda-core-example:`CUDA graph ` example. +- Add a :cuda-core-example:`memory resource ` example. Fixes and enhancements diff --git a/cuda_pathfinder/docs/build_docs.sh b/cuda_pathfinder/docs/build_docs.sh index a7889b58dda..4720cd458f6 100755 --- a/cuda_pathfinder/docs/build_docs.sh +++ b/cuda_pathfinder/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 @@ -25,8 +25,17 @@ if [[ -z "${SPHINX_CUDA_PATHFINDER_VER}" ]]; then | awk -F'+' '{print $1}') fi +if [[ "${LATEST_ONLY}" == "1" && -z "${BUILD_PREVIEW:-}" && -z "${BUILD_LATEST:-}" ]]; then + export BUILD_LATEST=1 +fi + # build the docs (in parallel) -SPHINXOPTS="-W --keep-going -j 4 -d build/.doctrees" make html +if [[ -z "${SPHINXOPTS:-}" ]]; then + HTML_SPHINXOPTS="-W --keep-going -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 diff --git a/cuda_pathfinder/docs/source/conf.py b/cuda_pathfinder/docs/source/conf.py index f794eb9ee2b..aa6cd964b54 100644 --- a/cuda_pathfinder/docs/source/conf.py +++ b/cuda_pathfinder/docs/source/conf.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (c) 2012-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-FileCopyrightText: Copyright (c) 2012-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 # Configuration file for the Sphinx documentation builder. @@ -26,6 +26,15 @@ release = os.environ["SPHINX_CUDA_PATHFINDER_VER"] +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-pathfinder/latest/" + if int(os.environ.get("BUILD_LATEST", 0)): + return f"{docs_domain}/cuda-pathfinder/latest/" + return f"{docs_domain}/cuda-pathfinder/{release}/" + + # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -65,7 +74,7 @@ # 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": { diff --git a/cuda_python/docs/build_docs.sh b/cuda_python/docs/build_docs.sh index 97be962a1a9..528b1c15c3a 100755 --- a/cuda_python/docs/build_docs.sh +++ b/cuda_python/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 @@ -25,6 +25,10 @@ if [[ -z "${SPHINX_CUDA_PYTHON_VER}" ]]; then | awk -F'+' '{print $1}') fi +if [[ "${LATEST_ONLY}" == "1" && -z "${BUILD_PREVIEW:-}" && -z "${BUILD_LATEST:-}" ]]; then + export BUILD_LATEST=1 +fi + # build the docs (in parallel) SPHINXOPTS="-j 4 -d build/.doctrees" make html diff --git a/cuda_python/docs/source/conf.py b/cuda_python/docs/source/conf.py index 454cec49732..1b1932be711 100644 --- a/cuda_python/docs/source/conf.py +++ b/cuda_python/docs/source/conf.py @@ -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 # Configuration file for the Sphinx documentation builder. @@ -26,6 +26,15 @@ release = os.environ["SPHINX_CUDA_PYTHON_VER"] +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']}/latest/" + if int(os.environ.get("BUILD_LATEST", 0)): + return f"{docs_domain}/latest/" + return f"{docs_domain}/{release}/" + + # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -58,7 +67,7 @@ # 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": { diff --git a/cuda_python/docs/source/release/12.9.5-notes.rst b/cuda_python/docs/source/release/12.9.5-notes.rst index a134a36f00e..aac1dfa7929 100644 --- a/cuda_python/docs/source/release/12.9.5-notes.rst +++ b/cuda_python/docs/source/release/12.9.5-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 12.9.5 Release notes @@ -8,7 +8,7 @@ CUDA Python 12.9.5 Release notes Included components ------------------- -* `cuda.bindings 12.9.5 `_ +* `cuda.bindings 12.9.5 `_ * `cuda.pathfinder 1.3.3 `_ diff --git a/cuda_python/docs/source/release/12.9.6-notes.rst b/cuda_python/docs/source/release/12.9.6-notes.rst index 86ed747cfc7..b66e1e9ad50 100644 --- a/cuda_python/docs/source/release/12.9.6-notes.rst +++ b/cuda_python/docs/source/release/12.9.6-notes.rst @@ -7,7 +7,7 @@ CUDA Python 12.9.6 Release notes Included components ------------------- -* `cuda.bindings 12.9.6 `_ +* `cuda.bindings 12.9.6 `_ * `cuda.pathfinder 1.4.2 `_ Known issues