Which Python documentation tool should I use?
The right tool depends on the site’s dominant job: what the content is, who writes it, and what the build pipeline can support.
For a new project whose contributors write Markdown, use Zensical (or MkDocs with Material for MkDocs). Add mkdocstrings for API reference. Choose Sphinx when semantic cross-references across projects or non-HTML output formats shape the site. Consider Great Docs when the API is the primary content and a system-level Quarto dependency is acceptable.
Existing MkDocs sites do not need an immediate rewrite. Keep the working MkDocs build while testing the same content and configuration with Zensical.
Match the tool to the project
| Project need | Pick | Main trade-off |
|---|---|---|
| Write tutorials and how-to guides in Markdown, with an API section | Zensical with mkdocstrings | Zensical does not yet replace every MkDocs plugin or custom template |
| Maintain a large API reference with semantic links across projects | Sphinx | Configuration and reStructuredText conventions add complexity, even when using MyST Markdown |
| Publish PDF or ePub from the same source | Sphinx | Its broader output model carries more concepts than an HTML-only site needs |
| Build a site whose primary content is a Python package’s public API | Great Docs | Pre-1.0, requires a system-level Quarto installation, smaller ecosystem |
| Preserve an existing Material for MkDocs site | MkDocs and Zensical together | The migration needs side-by-side output checks before changing production |
Choose Zensical or MkDocs for a Markdown-first site
Zensical preserves the MkDocs project model: Markdown content, a static site, and configuration in mkdocs.yml or zensical.toml. It supports Material settings and provides native implementations for selected MkDocs plugins, including mkdocstrings integration. Python API rendering also requires the mkdocstrings-python package.
Choose Zensical for a new site when prose is the main content and contributors already write Markdown. The generated API can remain one section rather than controlling the site’s structure. The basic HTML build installs through pip or uv and does not require Quarto.
Plugin compatibility is the boundary. Zensical ignores configuration for unsupported MkDocs plugins instead of running them, so a successful build does not prove feature parity. Check the plugin compatibility list before depending on a plugin, and inspect the rendered feature it controls.
Choose Sphinx for semantic references and multiple outputs
Sphinx treats documented Python objects, sections, citations, and glossary terms as named targets. Its intersphinx extension carries those references across projects, while autodoc builds API pages from docstrings. Dedicated builders produce HTML and ePub; the LaTeX builder produces source files that require a separate LaTeX installation to compile into PDF.
Those capabilities matter for large libraries whose documentation acts as a connected reference system. CPython, NumPy, and SciPy publish working examples of Sphinx configurations and extensions.
Sphinx reads reStructuredText by default. MyST adds Markdown, but many extensions and examples still assume Sphinx directives and roles. Do not pick Sphinx only because it is established; pick it when its reference model or output formats solve a requirement.
Consider Great Docs when the API is the primary content
Great Docs scans a Python package, discovers its public objects, and generates a landing page, API reference, and navigation. It also produces llms.txt and agent-skill output. It supports authored narrative pages and user guides in Quarto Markdown, with generated navigation and nested sections.
Three constraints shape whether it fits. Great Docs uses Quarto as its rendering engine, so contributors and CI need a system-level Quarto installation alongside the Python package. It is pre-1.0 with a smaller ecosystem of themes and extensions than Sphinx or MkDocs. Read the Docs does not support it natively; use GitHub Pages or configure a custom Read the Docs build.
Pick Great Docs when the API is the primary content and contributors can install Quarto. Prefer Zensical or MkDocs when prose is the main content; choose Sphinx when semantic references or multiple output formats matter. Choose another tool when the Quarto dependency is impractical or you need Read the Docs’ built-in Sphinx/MkDocs workflow.
Keep MkDocs during a Zensical migration
Material for MkDocs is in maintenance mode, with feature development moved to Zensical. Zensical can read an existing mkdocs.yml, standard docs/ layout, Python Markdown content, and supported plugin configuration.
Treat that compatibility as a migration path rather than a promise that every site renders identically. Keep the MkDocs production build, add a Zensical build beside it, and compare navigation, search, redirects, and representative pages. Switch the production command only after each plugin and template override has a verified replacement.
MkDocs remains a reasonable maintenance choice while an existing site works. For a new site, Zensical avoids choosing a theme whose feature development has ended.
Put the decision into practice
For Sphinx or MkDocs, follow How to Set Up Documentation for a Python Package. It creates the documentation dependency group, API page, and local preview.
Zensical scaffolds a Markdown site with zensical new; Great Docs discovers a package with great-docs init. Follow the Zensical getting-started guide or Great Docs setup instructions for prerequisites and build commands. Whichever path you choose, run the production build in CI and fail on unresolved references or broken links.