docs: add pixi docs env and clean repo-owned warnings (#1870)

* docs: add pixi docs env and clean repo-owned warnings

Add reproducible Pixi docs workflows for pathfinder, bindings, and core, and fix the warnings in source-owned docs and shared Sphinx extensions. Keep generated bindings module docs out of scope so the remaining warning set stays isolated to code generator output.

Made-with: Cursor

* style: apply ruff formatting fixes

Apply the formatter changes required by pre-commit.ci so the docs helper updates match repository formatting rules.

Made-with: Cursor

* docs: fail pathfinder and core builds on warnings

Enable `-W --keep-going` for the pathfinder and core Sphinx builds so warning regressions fail the docs workflow while still reporting the full warning set.

Made-with: Cursor

* docs: dedupe cuda_core docs task wiring

Remove the redundant cuda_core build-docs alias and point the repo-root docs task at the canonical docs-build target so the post-rebase docs workflow stays consistent.

Made-with: Cursor

Author: cpcloud

.gitignore

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

cuda_bindings/docs/source/conf.py

@@ -9,6 +9,7 @@
 
 # -- Path setup --------------------------------------------------------------
 
+import inspect
 import os
 import sys
 from pathlib import Path
@@ -103,7 +104,7 @@ def _github_examples_ref():
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []  # ["_static"] does not exist in our environment
 
 # skip cmdline prompts
 copybutton_exclude = ".linenos, .gp"
@@ -120,7 +121,45 @@ def _github_examples_ref():
     "cufile": ("https://docs.nvidia.com/gpudirect-storage/api-reference-guide/", None),
 }
 
+
+def _sanitize_generated_docstring(lines):
+    doc_lines = inspect.cleandoc("\n".join(lines)).splitlines()
+    if not doc_lines:
+        return
+
+    if "(" in doc_lines[0] and ")" in doc_lines[0]:
+        doc_lines = doc_lines[1:]
+        while doc_lines and not doc_lines[0].strip():
+            doc_lines.pop(0)
+
+    if not doc_lines:
+        lines[:] = []
+        return
+
+    lines[:] = [".. code-block:: text", ""]
+    lines.extend(f"   {line}" if line else "   " for line in doc_lines)
+
+
+def autodoc_process_docstring(app, what, name, obj, options, lines):
+    if name.startswith("cuda.bindings."):
+        _sanitize_generated_docstring(lines)
+
+
+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
+
+
 suppress_warnings = [
     # for warnings about multiple possible targets, see NVIDIA/cuda-python#152
     "ref.python",
 ]
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", autodoc_process_docstring)
+    app.connect("source-read", rewrite_source)

cuda_bindings/docs/source/contribute.rst

@@ -4,12 +4,17 @@
 Contributing
 ============
 
-Thank you for your interest in contributing to ``cuda-bindings``! Based on the type of contribution, it will fall into two categories:
-
-1. You want to report a bug, feature request, or documentation issue
-    - File an `issue <https://github.com/NVIDIA/cuda-python/issues/new/choose>`_ describing what you encountered or what you want to see changed.
-    - The NVIDIA team will evaluate the issues and triage them, scheduling
-    them for a release. If you believe the issue needs priority attention
-    comment on the issue to notify the team.
-2. You want to implement a feature, improvement, or bug fix:
-    - At this time we do not accept code contributions.
+Thank you for your interest in contributing to ``cuda-bindings``! Based on the
+type of contribution, it will fall into two categories:
+
+1. You want to report a bug, feature request, or documentation issue.
+
+   File an `issue <https://github.com/NVIDIA/cuda-python/issues/new/choose>`_
+   describing what you encountered or what you want to see changed. The NVIDIA
+   team will evaluate the issue, triage it, and schedule it for a release. If
+   you believe the issue needs priority attention, comment on the issue to
+   notify the team.
+
+2. You want to implement a feature, improvement, or bug fix.
+
+   At this time we do not accept code contributions.

cuda_bindings/docs/source/install.rst

@@ -78,7 +78,7 @@ Installing from Source
 ----------------------
 
 Requirements
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 * CUDA Toolkit headers[^1]
 * CUDA Runtime static library[^2]
@@ -100,7 +100,7 @@ See `Environment Variables <environment_variables.rst>`_ for a description of ot
    Only ``cydriver``, ``cyruntime`` and ``cynvrtc`` are impacted by the header requirement.
 
 Editable Install
-^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~
 
 You can use:
 

cuda_bindings/docs/source/overview.rst

@@ -25,9 +25,9 @@ code into
 `PTX <https://docs.nvidia.com/cuda/parallel-thread-execution/index.html>`_ and
 then extract the function to be called at a later point in the application. You
 construct your device code in the form of a string and compile it with
-`NVRTC <http://docs.nvidia.com/cuda/nvrtc/index.html>`_, a runtime compilation
+`NVRTC <https://docs.nvidia.com/cuda/nvrtc/index.html>`_, a runtime compilation
 library for CUDA C++. Using the NVIDIA `Driver
-API <http://docs.nvidia.com/cuda/cuda-driver-api/index.html>`_, manually create a
+API <https://docs.nvidia.com/cuda/cuda-driver-api/index.html>`_, manually create a
 CUDA context and all required resources on the GPU, then launch the compiled
 CUDA C++ code and retrieve the results from the GPU. Now that you have an
 overview, jump into a commonly used example for parallel programming:
@@ -428,7 +428,7 @@ Putting it all together:
    )
 
 The final step is to construct a ``kernelParams`` argument that fulfills all of the launch API conditions. This is made easy because each array object comes
-with a `ctypes <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.ctypes.html#numpy.ndarray.ctypes>`_ data attribute that returns the underlying ``void*`` pointer value.
+with NumPy's `ctypes data attribute <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.ctypes.html#numpy.ndarray.ctypes>`_ that returns the underlying ``void*`` pointer value.
 
 By having the final array object contain all pointers, we fulfill the contiguous array requirement:
 

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

@@ -2,7 +2,7 @@
 .. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 ``cuda-bindings`` 11.8.6 Release notes
-====================================
+==========================================
 
 Released on January 24, 2025.
 

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

@@ -2,7 +2,7 @@
 .. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 ``cuda-bindings`` 12.8.0 Release notes
-====================================
+==========================================
 
 Released on January 24, 2025.