Python documentation tools compared

Most Python projects need two kinds of docs. API reference describes each module, class, and function, and is best generated from docstrings so it cannot disagree with the signatures. Narrative docs explain how the project fits together: setup, architecture, request flows, conventions, and how to run the checks.

The classic generators are strongest at the first job. They will happily host the second, but someone has to write those pages by hand and remember to update them.

Sphinx is the long-standing default for Python libraries and the tool behind the Python docs themselves. autodoc pulls docstrings into pages, napoleon understands Google and NumPy docstring styles, and intersphinx links your reference to other projects. reStructuredText is the native markup; MyST-Parser adds Markdown.

Pick Sphinx for a public library that needs deep, cross-linked reference and versioned hosting on Read the Docs. Expect more configuration than the alternatives.

MkDocs builds a site from Markdown files and a mkdocs.yml config, and mkdocstrings adds API reference generated from docstrings. Many teams prefer it to Sphinx because the docs are plain Markdown.

One thing to plan for: Material for MkDocs, the theme most MkDocs sites use, went into maintenance mode in November 2025. Its team now builds Zensical, a successor designed to read existing mkdocs.yml configs, and Material's critical fixes are only promised through November 2026. If you are starting a new MkDocs site, check where Zensical and your plugins stand first.

pdoc is the low-effort option: point it at a package and it renders HTML reference from docstrings and type annotations with no config. It is a good fit for internal packages and small libraries that do not need a full narrative site.

pydoc ships with Python. python -m pydoc shows help in the terminal or serves basic HTML pages. It is handy for a quick look, not for published docs.

Docstring reference stays honest because it is rebuilt from the code. The narrative pages do not: the setup guide still says pip install after the move to uv, the architecture page lists a router that was split in two, and the conventions page predates the switch to Pydantic v2.

This is the part a generator cannot fix, because the problem is not rendering. Something has to tie each page to the code it describes and flag it when that code changes.