Skip to content

📝 docs(sphinx): add Sphinx documentation site#557

Merged
gaborbernat merged 1 commit intotox-dev:mainfrom
gaborbernat:docs
Mar 23, 2026
Merged

📝 docs(sphinx): add Sphinx documentation site#557
gaborbernat merged 1 commit intotox-dev:mainfrom
gaborbernat:docs

Conversation

@gaborbernat
Copy link
Copy Markdown
Member

pipdeptree's documentation has lived entirely in README.md, which made it hard to organize growing content like output format examples, CLI reference, and usage patterns into a discoverable structure.

📝 This adds a full Sphinx documentation site using the furo theme, mirroring the virtualenv project's docs setup. The site follows the Diataxis framework with tutorial, how-to guides, reference, and explanation sections. Every pipdeptree command example shows real output from the dev environment so nothing is fabricated. The CLI reference uses sphinx-argparse-cli to auto-generate from the argparse parser, keeping it permanently in sync with the code. Mermaid diagrams throughout visualize dependency graphs, conflict detection, and the internal architecture.

🔧 Build infrastructure includes a tox -e docs environment with sphinx-build -W (warnings as errors), a .readthedocs.yml for RTD hosting, and docs added to the CI matrix. Also fixes the mermaid renderer to use <br/> instead of \n for node label line breaks, since Mermaid's JS renderer treats \n as literal text.

pipdeptree's documentation lived entirely in README.md, limiting
discoverability and making it hard to organize growing content like
output format examples and CLI reference.

Sphinx with furo theme mirrors the virtualenv project's docs setup and
enables ReadTheDocs hosting. All examples use real pipdeptree output
from the dev environment. sphinx-argparse-cli auto-generates the CLI
reference from the argparse parser so it stays in sync with the code.

Also fixes mermaid output to use <br/> instead of \n for node label
line breaks, since Mermaid's JS renderer treats \n as literal text.
@gaborbernat gaborbernat enabled auto-merge (squash) March 23, 2026 18:04
@gaborbernat gaborbernat merged commit a3fad7b into tox-dev:main Mar 23, 2026
11 checks passed
@gaborbernat gaborbernat deleted the docs branch March 23, 2026 18:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant