Overhaul Sphinx documentation

[mmccarty]

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

[mmccarty]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Walkthrough

A comprehensive documentation infrastructure is established for the RAPIDS CLI project, including Sphinx configuration updates, API reference documentation for core modules, user guides, developer plugin documentation, troubleshooting guides, and documentation build dependencies.

Changes

Cohort / File(s)	Summary
Documentation Build Configuration CLAUDE.md, dependencies.yaml, docs/source/conf.py	Adds documentation build setup: build/view/clean commands in CLAUDE.md, introduces docs dependency group with sphinx, pydata-sphinx-theme, and sphinx-copybutton in dependencies.yaml, and significantly enhances Sphinx configuration with autodoc, napoleon, intersphinx, copybutton extensions, pydata_sphinx_theme, Google-style docstring parsing, dynamic copyright metadata, and custom setup hook for CSS/JS injection.
API Reference Documentation docs/source/api/cli.rst, docs/source/api/debug.rst, docs/source/api/doctor.rst, docs/source/api/checks.rst	Introduces new API documentation files describing core RAPIDS CLI modules: cli entry point, debug system information collection, doctor health check orchestration, and built-in health check implementations with automodule directives.
User and Developer Guides docs/source/index.rst, docs/source/user_guide.rst, docs/source/plugin_development.rst, docs/source/troubleshooting.rst	Restructures documentation index with User Guide, Developer Guide, and API Reference sections; adds user_guide.rst with rapids doctor and rapids debug command usage; introduces plugin_development.rst with plugin authoring guidelines and check function contract; adds troubleshooting.rst with GPU detection, CUDA version, memory, and custom check discovery issues.
Documentation Reorganization docs/source/cuda_driver.rst, docs/source/doctor.rst	Removes standalone cuda_driver.rst and doctor.rst documentation pages, consolidating content into the new API reference structure under docs/source/api/.
Docstring Enhancement rapids_cli/doctor/doctor.py	Updates doctor_check function docstring to use explicit Args section, improves formatting of Raises and Notes sections, and updates Example block for clarity without altering function logic or signature.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• jacobtomlinson
• jameslamb

Poem

🐰 Sphinx and docs now bloom so bright,
Configuration set just right,
API guides, user tales,
Plugin paths and troubleshoot trails,
Documentation's here to stay! ✨📚

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Overhaul Sphinx documentation' directly summarizes the main objective of the PR, which is a comprehensive restructuring and enhancement of the Sphinx documentation system.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@docs/source/api/debug.rst`:
- Line 10: Replace the bare reference to run_debug with a fully qualified Sphinx
cross-reference using the module path used in the automodule
(rapids_cli.debug.debug); update the text to use the form
~rapids_cli.debug.debug.run_debug so Sphinx resolves with the full path but
displays only the short name `run_debug`, ensuring consistency with ..
automodule:: rapids_cli.debug.debug.

In `@docs/source/api/doctor.rst`:
- Line 12: The short-form cross-reference :class:`CheckResult` may not resolve —
replace it with the fully-qualified Sphinx reference that includes the module
path (e.g. :class:`your_package.module.CheckResult`) or use the same resolution
pattern applied for :func:`run_debug` in debug.rst; ensure the module path
matches the actual import location of CheckResult or add a suitable ..
currentmodule:: directive so the class reference resolves correctly.

In `@rapids_cli/doctor/doctor.py`:
- Around line 42-43: Remove the incorrect "Raises: ValueError" section from the
docstring of the doctor_check function; doctor_check catches all exceptions (via
the except Exception as e: path) and records them in the CheckResult object
instead of propagating, so update the docstring in doctor_check to reflect that
it returns a bool/CheckResult rather than raising, and do not add any new raise
statements—leave exception handling to the individual check modules (e.g.,
gpu.py, nvlink.py) which may raise internally.

🧹 Nitpick comments (1)

docs/source/conf.py (1)

74-81: External resource loading looks intentional for RAPIDS branding; consider pinning Font Awesome with SRI.

The setup() hook loads CSS/JS from docs.rapids.ai (first-party) and Font Awesome 5.9.0 from cdnjs. This is standard for org-wide docs branding.

Two optional notes:

• Font Awesome 5.9.0 is quite dated (FA 6.x has been available for years). If the RAPIDS custom CSS depends on FA 5.x class names, this is fine — otherwise consider updating.
• For the cdnjs resource, you could add a Subresource Integrity hash if Sphinx's add_css_file supports an integrity attribute, to guard against CDN tampering.

Neither is blocking.

[jacobtomlinson]

Thanks for this!

I left some comments. I tried to write them in a way that should be actionable for an agent.

[mmccarty]

Thanks @jacobtomlinson

Just a note, CodeRabbit give Agent prompts that start with "@rapids_cli/" around lines x - y" to help the Agent fine the specific location of the feedback. Even less typing for the humans!

[jameslamb]

Left some minor comments, giving this a packaging-codeowners approval so you can do what you want with them and not need another review from me.

Will defer to Jacob and Naty on the actual content of the docs.

[jameslamb]

For my education... what's the purpose of changing this from numpydoc format to this format? Does it change how the docs are rendered in the API reference?

[mmccarty]

Claude says...

● The project's ruff configuration enforces Google-style docstrings via the pydocstyle convention. Let me show the relevant config:

● Searched for 1 pattern (ctrl+o to expand)

● The ruff linter is configured with convention = "google" at pyproject.toml:131. The D rule set (pydocstyle) enforces this, so any NumPy-style
docstrings (which use section headers like Parameters\n----------) would fail ruff checks. Google-style uses Args:, Returns:, Raises: with indented
descriptions instead.

The doctor_check() docstring was the one that still had a NumPy-style Raises section that we corrected (and replaced with Returns since the function
doesn't actually raise).