Preview will be ready when the GitHub Pages deployment is complete.
# The steps below are executed only when building on main.
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index ed58b4f260..37fa211593 100644
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -19,6 +19,7 @@ on:
# - cuda-core
# - cuda-bindings
# - cuda-python
+ # - cuda-pathfinder
# - all
git-tag:
description: "Target git tag to build docs for"
diff --git a/.gitignore b/.gitignore
index a9e5941f67..53c2e4f358 100644
--- a/.gitignore
+++ b/.gitignore
@@ -115,6 +115,7 @@ instance/
# Sphinx documentation
docs_src/_build/
+*/docs/source/generated/
# PyBuilder
.pybuilder/
diff --git a/README.md b/README.md
index 5f8f3a11e1..cffa52f2e4 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ CUDA Python is the home for accessing NVIDIA’s CUDA platform from Python. It c
* [cuda.core](https://nvidia.github.io/cuda-python/cuda-core/latest): Pythonic access to CUDA Runtime and other core functionalities
* [cuda.bindings](https://nvidia.github.io/cuda-python/cuda-bindings/latest): Low-level Python bindings to CUDA C APIs
-* [cuda.pathfinder](https://github.com/NVIDIA/cuda-python/blob/main/cuda_pathfinder/cuda/pathfinder/README.md): Utilities for locating CUDA components installed in the user's Python environment
+* [cuda.pathfinder](https://nvidia.github.io/cuda-python/cuda-pathfinder/latest): Utilities for locating CUDA components installed in the user's Python environment
* [cuda.cccl.cooperative](https://nvidia.github.io/cccl/python/cooperative): A Python module providing CCCL's reusable block-wide and warp-wide *device* primitives for use within Numba CUDA kernels
* [cuda.cccl.parallel](https://nvidia.github.io/cccl/python/parallel): A Python module for easy access to CCCL's highly efficient and customizable parallel algorithms, like `sort`, `scan`, `reduce`, `transform`, etc. that are callable on the *host*
* [numba.cuda](https://nvidia.github.io/numba-cuda/): Numba's target for CUDA GPU programming by directly compiling a restricted subset of Python code into CUDA kernels and device functions following the CUDA execution model.
diff --git a/cuda_bindings/docs/README.md b/cuda_bindings/docs/README.md
index a5e65842a8..54d670d091 100644
--- a/cuda_bindings/docs/README.md
+++ b/cuda_bindings/docs/README.md
@@ -1,11 +1,11 @@
# Build the documentation
1. Install the `cuda-bindings` package of the version that we need to document.
-2. Ensure the version is included in the [`versions.json`](./versions.json).
+2. Ensure the version is included in the [`nv-versions.json`](./nv-versions.json).
3. Build the docs with `./build_docs.sh`.
4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`.
Alternatively, we can build all the docs at once by running [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh).
To publish the docs with the built version, it is important to note that the html files of older versions
-should be kept intact, in order for the version selection (through `versions.json`) to work.
+should be kept intact, in order for the version selection (through `nv-versions.json`) to work.
diff --git a/cuda_bindings/docs/source/release/13.X.Y-notes.rst b/cuda_bindings/docs/source/release/13.X.Y-notes.rst
index 4cf9bd9405..0e0e82badd 100644
--- a/cuda_bindings/docs/source/release/13.X.Y-notes.rst
+++ b/cuda_bindings/docs/source/release/13.X.Y-notes.rst
@@ -16,7 +16,7 @@ Highlights
* Automatic CUDA library path detection based on ``CUDA_HOME``, eliminating the need to manually set ``LIBRARY_PATH`` environment variables for installation.
* The ``[all]`` optional dependencies now use ``cuda-toolkit`` with appropriate extras instead of individual packages. The NVCC compiler is no longer automatically installed with ``pip install cuda-python[all]`` as it was previously included only to access the NVVM library, which now has its own dedicated wheel. Users who need the NVCC compiler should explicitly install it with ``pip install cuda-toolkit[nvcc]==X.Y`` with the appropriate version for their needs.
-* The Python overhead of calling functions in CUDA bindings in `driver`, `runtime` and `nvrtc` has been reduced by approximately 30%.
+* The Python overhead of calling functions in CUDA bindings in ``driver``, ``runtime`` and ``nvrtc`` has been reduced by approximately 30%.
Known issues
diff --git a/cuda_core/docs/README.md b/cuda_core/docs/README.md
index 7402ba68e5..a4c0aacf6f 100644
--- a/cuda_core/docs/README.md
+++ b/cuda_core/docs/README.md
@@ -1,11 +1,11 @@
# Build the documentation
1. Install the `cuda-core` package of the version that we need to document.
-2. Ensure the version is included in the [`versions.json`](./versions.json).
+2. Ensure the version is included in the [`nv-versions.json`](./nv-versions.json).
3. Build the docs with `./build_docs.sh`.
4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`.
Alternatively, we can build all the docs at once by running [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh).
To publish the docs with the built version, it is important to note that the html files of older versions
-should be kept intact, in order for the version selection (through `versions.json`) to work.
+should be kept intact, in order for the version selection (through `nv-versions.json`) to work.
diff --git a/cuda_pathfinder/cuda/pathfinder/README.md b/cuda_pathfinder/cuda/pathfinder/README.md
index ebed211fef..c020fc6a23 100644
--- a/cuda_pathfinder/cuda/pathfinder/README.md
+++ b/cuda_pathfinder/cuda/pathfinder/README.md
@@ -1,45 +1,3 @@
-# `cuda.pathfinder` Module
+### The `cuda.pathfinder` documentation was moved
-## Public API for loading NVIDIA Dynamic Libs
-
-* `cuda.pathfinder.SUPPORTED_NVIDIA_LIBNAMES` (`tuple[str]`)
-
-* `cuda.pathfinder.load_nvidia_dynamic_lib(libname: str) -> LoadedDL`
-
-* `cuda.pathfinder.LoadedDL`:
- * `abs_path` (`str`)
- * `was_already_loaded_from_elsewhere` (`bool`)
-
-* `cuda.pathfinder.DynamicLibNotFoundError` (inherits from `RuntimeError`)
-
-## Dynamic Library Loading Search Priority
-
-The `cuda.pathfinder.load_nvidia_dynamic_lib` function implements a
-hierarchical search strategy for locating NVIDIA shared libraries:
-
-0. **Check if a library was loaded into the process already by some other means.**
- - If yes, there is no alternative to skipping the rest of the search logic.
- The absolute path of the already loaded library will be returned, along
- with the handle to the library.
-
-1. **NVIDIA Python wheels**
- - Scans all site-packages to find libraries installed via NVIDIA Python wheels.
-
-2. **OS default mechanisms / Conda environments**
- - Falls back to native loader:
- - `dlopen()` on Linux
- - `LoadLibraryW()` on Windows
- - Conda installations are expected to be discovered:
- - Linux: Via `$ORIGIN/../lib` on `RPATH` (of the `python` binary;
- note that this preempts `LD_LIBRARY_PATH` and `/etc/ld.so.conf.d/`)
- - Windows: Via `%CONDA_PREFIX%\Library\bin` on system `PATH`
- - CTK installations with system config updates are expected to be discovered:
- - Linux: Via `/etc/ld.so.conf.d/*cuda*.conf`
- - Windows: Via `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y\bin` on system `PATH`
-
-3. **Environment variables**
- - Relies on `CUDA_HOME` or `CUDA_PATH` environment variables if set
- (in that order).
-
-Note that the search is done on a per-library basis. Currently there is no
-centralized mechanism that ensures all libraries are found in the same way.
+Please see https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/
diff --git a/cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py b/cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py
index 29f2654608..3160333aa9 100644
--- a/cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py
+++ b/cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py
@@ -53,16 +53,62 @@ def _load_lib_no_cache(libname: str) -> LoadedDL:
@functools.cache
def load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
- """Load a NVIDIA dynamic library by name.
+ """Load an NVIDIA dynamic library by name.
Args:
- libname: The name of the library to load (e.g. "cudart", "nvvm", etc.)
+ libname (str): The short name of the library to load (e.g., ``"cudart"``,
+ ``"nvvm"``, etc.).
Returns:
- A LoadedDL object containing the library handle and path
+ LoadedDL: Object containing the OS library handle and absolute path.
Raises:
- RuntimeError: If the library cannot be found or loaded
+ DynamicLibNotFoundError: If the library cannot be found or loaded.
+ RuntimeError: If Python is not 64-bit.
+
+ Search order:
+ 0. **Already loaded in the current process**
+
+ - If a matching library is already loaded by some other component,
+ return its absolute path and handle and skip the rest of the search.
+
+ 1. **NVIDIA Python wheels**
+
+ - Scan installed distributions (``site-packages``) to find libraries
+ shipped in NVIDIA wheels.
+
+ 2. **OS default mechanisms / Conda environments**
+
+ - Fall back to the native loader:
+
+ - Linux: ``dlopen()``
+
+ - Windows: ``LoadLibraryW()``
+
+ - Conda installations are commonly discovered via:
+
+ - Linux: ``$ORIGIN/../lib`` in the ``RPATH`` of the ``python`` binary
+ (note: this can take precedence over ``LD_LIBRARY_PATH`` and
+ ``/etc/ld.so.conf.d/``).
+
+ - Windows: ``%CONDA_PREFIX%\\Library\\bin`` on the system ``PATH``.
+
+ - CUDA Toolkit (CTK) system installs with system config updates are often
+ discovered via:
+
+ - Linux: ``/etc/ld.so.conf.d/*cuda*.conf``
+
+ - Windows: ``C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\vX.Y\\bin``
+ on the system ``PATH``.
+
+ 3. **Environment variables**
+
+ - If set, use ``CUDA_HOME`` or ``CUDA_PATH`` (in that order).
+
+ Notes:
+ The search is performed **per library**. There is currently no mechanism to
+ guarantee that multiple libraries are all resolved from the same location.
+
"""
pointer_size_bits = struct.calcsize("P") * 8
if pointer_size_bits != 64:
diff --git a/cuda_pathfinder/docs/Makefile b/cuda_pathfinder/docs/Makefile
new file mode 100644
index 0000000000..3d73179c53
--- /dev/null
+++ b/cuda_pathfinder/docs/Makefile
@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: Copyright (c) 2021-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?= -j auto
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build/html/${SPHINX_CUDA_PATHFINDER_VER}
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -b help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/cuda_pathfinder/docs/README.md b/cuda_pathfinder/docs/README.md
new file mode 100644
index 0000000000..47b62fc677
--- /dev/null
+++ b/cuda_pathfinder/docs/README.md
@@ -0,0 +1,11 @@
+# Build the documentation
+
+1. Install the `cuda-pathfinder` package of the version that we need to document.
+2. Ensure the version is included in the [`nv-versions.json`](./nv-versions.json).
+3. Build the docs with `./build_docs.sh`.
+4. The html artifacts should be available under both `./build/html/latest` and `./build/html/`.
+
+Alternatively, we can build all the docs at once by running [`cuda_python/docs/build_all_docs.sh`](../../cuda_python/docs/build_all_docs.sh).
+
+To publish the docs with the built version, it is important to note that the html files of older versions
+should be kept intact, in order for the version selection (through `nv-versions.json`) to work.
diff --git a/cuda_pathfinder/docs/build_docs.sh b/cuda_pathfinder/docs/build_docs.sh
new file mode 100755
index 0000000000..3d70cd5580
--- /dev/null
+++ b/cuda_pathfinder/docs/build_docs.sh
@@ -0,0 +1,50 @@
+#!/bin/bash
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -ex
+
+if [[ "$#" == "0" ]]; then
+ LATEST_ONLY="0"
+elif [[ "$#" == "1" && "$1" == "latest-only" ]]; then
+ LATEST_ONLY="1"
+else
+ echo "usage: ./build_docs.sh [latest-only]"
+ exit 1
+fi
+
+# SPHINX_CUDA_PATHFINDER_VER is used to create a subdir under build/html
+# (the Makefile file for sphinx-build also honors it if defined).
+# If there's a post release (ex: .post1) we don't want it to show up in the
+# version selector or directory structure.
+if [[ -z "${SPHINX_CUDA_PATHFINDER_VER}" ]]; then
+ export SPHINX_CUDA_PATHFINDER_VER=$(python -c "from importlib.metadata import version; \
+ ver = '.'.join(str(version('cuda-pathfinder')).split('.')[:3]); \
+ print(ver)" \
+ | awk -F'+' '{print $1}')
+fi
+
+# build the docs (in parallel)
+SPHINXOPTS="-j 4 -d build/.doctrees" 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
+# obsecure Sphinx errors
+#SPHINXOPTS="-v" make html
+
+# to support version dropdown menu
+cp ./nv-versions.json build/html
+
+# to have a redirection page (to the latest docs)
+cp source/_templates/main.html build/html/index.html
+
+# ensure that the latest docs is the one we built
+if [[ $LATEST_ONLY == "0" ]]; then
+ cp -r build/html/${SPHINX_CUDA_PATHFINDER_VER} build/html/latest
+else
+ mv build/html/${SPHINX_CUDA_PATHFINDER_VER} build/html/latest
+fi
+
+# ensure that the Sphinx reference uses the latest docs
+cp build/html/latest/objects.inv build/html
diff --git a/cuda_pathfinder/docs/nv-versions.json b/cuda_pathfinder/docs/nv-versions.json
new file mode 100644
index 0000000000..1b38475786
--- /dev/null
+++ b/cuda_pathfinder/docs/nv-versions.json
@@ -0,0 +1,6 @@
+[
+ {
+ "version": "latest",
+ "url": "https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/"
+ }
+]
diff --git a/cuda_pathfinder/docs/source/_templates/main.html b/cuda_pathfinder/docs/source/_templates/main.html
new file mode 100644
index 0000000000..38a8d2d642
--- /dev/null
+++ b/cuda_pathfinder/docs/source/_templates/main.html
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
+
+