Overhaul Sphinx documentation (#136)

## Summary

- Overhaul Sphinx docs: add user guide, troubleshooting guide, plugin
development guide, and full API reference (cli, doctor, debug, checks)
- Switch Sphinx theme to pydata-sphinx-theme with RAPIDS branding,
enable autodoc/napoleon/intersphinx/viewcode extensions
- Remove stale doc pages (old `doctor.rst`, `cuda_driver.rst`) and
restructure `index.rst` with proper toctree sections
- Fix `doctor_check()` docstring from NumPy-style to Google-style
(matches ruff pydocstyle convention)
- Add SPDX license headers to docs and `dependencies.yaml`
- Fix Sphinx cross-references for `run_debug` and `CheckResult` to use
fully qualified module paths
- Add `sphinx-llm` extension to generate `llms.txt` for LLM consumption
- Add `sphinx-autobuild` with `make serve` target for live-reload docs
development
- Rewrite doctor.rst with user-facing content explaining cross-layer
compatibility checks and library-bundled health checks
- Move check execution flow details to plugin_development.rst
- Fix incorrect `Raises` section in `doctor_check` docstring (replace
with `Returns`)

Note: This branch also includes the commits from #135 (unit tests and
coverage). The docs-specific changes are in commits after `2137644`.

## Test plan

- [ ] `make -C docs clean html` builds with 0 warnings
- [ ] `pre-commit run --all-files` passes
- [ ] `llms.txt` and `llms-full.txt` generated in build output
- [ ] `make serve` starts live-reload server

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: Mike McCarty <mmccarty@nvidia.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: James Lamb <jaylamb20@gmail.com>

Author: 3 people

CLAUDE.md

@@ -39,6 +39,19 @@ coverage report
 coverage html && open htmlcov/index.html
 ```
 
+### Documentation
+
+```bash
+# Build HTML documentation
+make -C docs html
+
+# Live-reload documentation server
+make -C docs serve
+
+# Remove build artifacts
+make -C clean
+```
+
 ### Linting and Pre-commit
 
 ```bash

dependencies.yaml

@@ -75,6 +75,15 @@ dependencies:
       - output_types: [pyproject, requirements]
         packages:
           - importlib-metadata >= 4.13.0; python_version < '3.12'
+  docs:
+    common:
+      - output_types: [conda, requirements, pyproject]
+        packages:
+          - pydata-sphinx-theme>=0.16.1
+          - sphinx>=8
+          - sphinx-autobuild>=2025.8.25
+          - sphinx-copybutton>=0.5.2
+          - sphinx-llm>=0.3.0
   test_python:
     common:
       - output_types: [conda, requirements, pyproject]

docs/Makefile

@@ -12,7 +12,10 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help serve Makefile
+
+serve:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/source/api/checks.rst

@@ -0,0 +1,42 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+Health Checks
+=============
+
+Built-in health check modules registered via the ``rapids_doctor_check``
+entry point group in ``pyproject.toml``.
+
+All check functions follow the contract described in :doc:`../plugin_development`.
+
+GPU Checks
+----------
+
+.. automodule:: rapids_cli.doctor.checks.gpu
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+CUDA Driver Checks
+------------------
+
+.. automodule:: rapids_cli.doctor.checks.cuda_driver
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Memory Checks
+-------------
+
+.. automodule:: rapids_cli.doctor.checks.memory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+NVLink Checks
+-------------
+
+.. automodule:: rapids_cli.doctor.checks.nvlink
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/cli.rst

@@ -0,0 +1,16 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+CLI Module
+==========
+
+The ``rapids_cli.cli`` module defines the main CLI entry point and subcommands
+using `rich-click <https://github.com/ewels/rich-click>`_.
+
+The CLI is registered as a console script called ``rapids`` via the
+``[project.scripts]`` entry in ``pyproject.toml``.
+
+.. automodule:: rapids_cli.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/debug.rst

@@ -0,0 +1,33 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+Debug Module
+============
+
+The ``rapids_cli.debug.debug`` module gathers system and environment information
+for troubleshooting RAPIDS installations.
+
+:func:`~rapids_cli.debug.debug.run_debug` is the main entry point. It collects:
+
+- Platform and OS details (from ``platform`` and ``/etc/os-release``)
+- NVIDIA driver and CUDA versions (via ``pynvml``)
+- CUDA runtime path (via ``cuda-pathfinder``)
+- System CUDA toolkit locations (globbing ``/usr/local/cuda*``)
+- Python version and hash info
+- All installed package versions
+- pip freeze and conda list output
+- Tool versions: pip, conda, uv, pixi, g++, cmake, nvcc
+
+Output is either a Rich-formatted console table or JSON (``--json``).
+
+Example:
+
+``rapids debug --json > "<name-output-file>.json"``
+
+API
+---
+
+.. automodule:: rapids_cli.debug.debug
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/doctor.rst

@@ -0,0 +1,48 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+Doctor Module
+=============
+
+The ``rapids_cli.doctor.doctor`` module orchestrates health check discovery
+and execution.
+
+The CUDA + Python software stack spans multiple layers — the GPU driver, the
+CUDA runtime, C/C++ libraries, and Python packages — each managed by different
+package managers (OS packages, CUDA toolkit installers, conda, pip). Because no
+single package manager owns the full stack, misconfigurations across layer
+boundaries are common and difficult to diagnose. ``rapids doctor`` validates
+compatibility across these layers, from the driver through CUDA to the Python
+libraries, and provides actionable feedback when an incompatibility is found.
+
+Health checks are bundled with the RAPIDS libraries you install rather than
+hard-coded into ``rapids-cli`` itself. When you install a library such as
+cuDF or cuML, any checks it ships are automatically available to
+``rapids doctor`` — no extra configuration required.
+
+You can run all discovered checks at once, or filter to a specific library
+by passing its name as an argument:
+
+.. code-block:: bash
+
+   # Run every available check
+   rapids doctor
+
+   # Run only checks related to cudf
+   rapids doctor cudf
+
+   # See which checks would run without executing them
+   rapids doctor --dry-run --verbose
+
+Results are collected into :class:`~rapids_cli.doctor.doctor.CheckResult`
+objects that track pass/fail status, return values, errors, and warnings.
+For details on how checks are discovered and executed, or how to write your
+own, see :doc:`/plugin_development`.
+
+API
+---
+
+.. automodule:: rapids_cli.doctor.doctor
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/conf.py

@@ -1,44 +1,82 @@
-# 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
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-
+import datetime
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../rapids_cli"))
+sys.path.insert(0, os.path.abspath("../../"))
 
+# -- Project information -----------------------------------------------------
 
 project = "RAPIDS CLI"
-copyright = "2024, NVIDIA RAPIDS"
-author = "NVIDIA RAPIDS"
-release = "2024"
+html_title = "RAPIDS CLI"
+copyright = f"{datetime.date.today().year}, NVIDIA"
+author = "NVIDIA"
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinx_llm.txt",
+]
 
 templates_path = ["_templates"]
 exclude_patterns = []
 
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
+# Napoleon settings for Google-style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
+# Autodoc settings
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
+html_theme = "pydata_sphinx_theme"
+
+html_theme_options = {
+    "header_links_before_dropdown": 7,
+    "icon_links": [],
+    "logo": {
+        "link": "https://docs.rapids.ai/",
+    },
+    "github_url": "https://github.com/rapidsai/rapids-cli",
+    "show_toc_level": 1,
+    "navbar_align": "right",
+}
+
+html_sidebars = {
+    "**": ["sidebar-nav-bs", "sidebar-ethical-ads"],
+}
+
 html_static_path = ["_static"]
 
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",  # For Google and NumPy style docstrings
-]
+
+def setup(app):
+    app.add_css_file("https://docs.rapids.ai/assets/css/custom.css")
+    app.add_css_file(
+        "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.9.0/css/all.min.css"
+    )
+    app.add_js_file(
+        "https://docs.rapids.ai/assets/js/custom.js", loading_method="defer"
+    )