Add Sphinx documentation for cuda.pathfinder

.github/actions/doc_preview/action.yml

@@ -41,7 +41,8 @@ runs:
  :---:
  | <p></p> :rocket: View preview at <br> https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/ <br>
  | <br> https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/cuda-core/ <br>
- | <br> https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/cuda-bindings/ <br><br>
+ | <br> https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/cuda-bindings/ <br>
+ | <br> https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/cuda-pathfinder/ <br><br>
  | <h6><br> Preview will be ready when the GitHub Pages deployment is complete. <br><br></h6>
 
  # The steps below are executed only when building on main.

.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"

.gitignore

@@ -115,6 +115,7 @@ instance/
 
 # Sphinx documentation
 docs_src/_build/
+*/docs/source/generated/
 
 # PyBuilder
 .pybuilder/

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.

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/<version>`.
 
 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.

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

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/<version>`.
 
 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.

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/

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:

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)

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/<version>`.
+
+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.

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

cuda_pathfinder/docs/nv-versions.json

@@ -0,0 +1,6 @@
+[
+ {
+ "version": "latest",
+ "url": "https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/"
+ }
+]

cuda_pathfinder/docs/source/_templates/main.html

@@ -0,0 +1,13 @@
+<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <meta http-equiv="refresh" content="0; url=latest/" />
+ <link rel="canonical" href="latest/" />
+ </head>
+ <body>
+ <p>If this page does not refresh automatically, then please direct your browser to
+ <a href="latest/">our latest cuda.pathfinder docs</a>.
+ </p>
+ </body>
+</html>

cuda_pathfinder/docs/source/api.rst

@@ -0,0 +1,20 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+.. module:: cuda.pathfinder
+
+``cuda.pathfinder`` API Reference
+=================================
+
+The ``cuda.pathfinder`` module provides utilities for loading NVIDIA dynamic libraries.
+
+Public API
+-----------
+
+.. autosummary::
+ :toctree: generated/
+
+ SUPPORTED_NVIDIA_LIBNAMES
+ load_nvidia_dynamic_lib
+ LoadedDL
+ DynamicLibNotFoundError