Improve docs: fix cross-refs, add sphinx-llm/autobuild, refine doctor page

- 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 dev
- 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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Mike McCarty <mmccarty@nvidia.com>

Author: mmccarty

CLAUDE.md

@@ -45,8 +45,8 @@ coverage html && open htmlcov/index.html
 # Build HTML documentation
 cd docs && make html
 
-# View documentation
-open docs/build/html/index.html
+# Live-reload documentation server
+cd docs && make serve
 
 # Clean build artifacts
 cd docs && make clean

dependencies.yaml

@@ -81,7 +81,9 @@ dependencies:
         packages:
           - pydata-sphinx-theme
           - sphinx
+          - sphinx-autobuild
           - sphinx-copybutton
+          - sphinx-llm
   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/debug.rst

@@ -7,7 +7,7 @@ Debug Module
 The ``rapids_cli.debug.debug`` module gathers system and environment information
 for troubleshooting RAPIDS installations.
 
-:func:`run_debug` is the main entry point. It collects:
+: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``)

docs/source/api/doctor.rst

@@ -7,27 +7,37 @@ Doctor Module
 The ``rapids_cli.doctor.doctor`` module orchestrates health check discovery
 and execution.
 
-Checks are discovered via Python entry points in the ``rapids_doctor_check``
-group. Each check function is called with ``verbose`` as a keyword argument.
-Results are collected into :class:`CheckResult` objects that track pass/fail
-status, return values, errors, and warnings.
+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.
 
-Check Execution Flow
---------------------
+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.
 
-1. **Discovery**: Scan ``rapids_doctor_check`` entry points and load check
-   functions. ``ImportError`` and ``AttributeError`` during loading are
-   silently suppressed via ``contextlib.suppress``.
+You can run all discovered checks at once, or filter to a specific library
+by passing its name as an argument:
 
-2. **Filtering**: If filter arguments are provided, only checks whose
-   ``ep.value`` contains a filter substring are kept.
+.. code-block:: bash
 
-3. **Execution**: Each check runs inside ``warnings.catch_warnings(record=True)``
-   so warnings are captured. Exceptions are caught and stored rather than
-   propagated.
+   # Run every available check
+   rapids doctor
 
-4. **Reporting**: Warnings are printed, verbose output is shown for passing
-   checks, and failed checks are listed with their error messages.
+   # 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
 ---

docs/source/conf.py

@@ -26,6 +26,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
+    "sphinx_llm.txt",
 ]
 
 templates_path = ["_templates"]

docs/source/plugin_development.rst

@@ -43,6 +43,25 @@ Quick Start
       pip install -e .
       rapids doctor --verbose --dry-run
 
+Check Execution Flow
+--------------------
+
+When ``rapids doctor`` runs, checks go through four stages:
+
+1. **Discovery**: Scan ``rapids_doctor_check`` entry points and load check
+   functions. ``ImportError`` and ``AttributeError`` during loading are
+   silently suppressed via ``contextlib.suppress``.
+
+2. **Filtering**: If filter arguments are provided, only checks whose
+   ``ep.value`` contains a filter substring are kept.
+
+3. **Execution**: Each check runs inside ``warnings.catch_warnings(record=True)``
+   so warnings are captured. Exceptions are caught and stored rather than
+   propagated.
+
+4. **Reporting**: Warnings are printed, verbose output is shown for passing
+   checks, and failed checks are listed with their error messages.
+
 Check Function Contract
 -----------------------
 

rapids_cli/doctor/doctor.py

@@ -39,8 +39,8 @@ def doctor_check(
         dry_run: Whether to skip running checks.
         filters: A list of filters to run specific checks.
 
-    Raises:
-        ValueError: If an invalid subcommand is provided.
+    Returns:
+        True if all checks passed (or dry_run is True), False otherwise.
 
     Note:
         The function discovers and loads check functions defined in entry points