sphinx-autodoc2

sphinx-autodoc2 is a Sphinx extension that automatically generates API documentation for Python packages by statically analyzing source files with astroid, rather than importing the target package the way Sphinx’s built-in autodoc does. Because it never imports anything, it correctly handles if TYPE_CHECKING blocks and other typing-only constructs, and it can even document packages living outside the current project by cloning them at build time.

The tool decouples analysis from rendering: source files are parsed once into a cached in-memory database of items, and that database is rendered into either reStructuredText or MyST Markdown output, so builds stay fast on incremental rebuilds. It follows __all__ to scope the public API, supports mixed rst/md docstrings within the same project, and ships a standalone autodoc2 CLI for generating documentation outside of a full Sphinx build.

What You Get

• Static analysis via astroid — no need to install or import the target package to document it, and if TYPE_CHECKING blocks are handled correctly
• Support for documenting external packages by cloning a git repo at a given ref (from_git_clone package config)
• Cached, incremental analysis and file rendering so rebuilds during active documentation work stay fast
• Native support for both reStructuredText and MyST (Markdown) docstrings, including mixing the two within one project
• A standalone autodoc2 CLI (autodoc2 list) for inspecting analysis output independent of a Sphinx build
• Sphinx directives (autodoc2-docstring, autodoc2-summary, autodoc2-object) for fine-grained manual documentation control

Common Use Cases

• Generating full API reference docs for a Python library as part of its Sphinx documentation site
• Documenting a package’s public API strictly via its __all__ exports, hiding internal helpers
• Building documentation for packages that are hard or slow to import (heavy C-extension or optional dependencies) since no import is required
• Migrating a docs project from rst to MyST Markdown docstrings incrementally, module by module
• Pulling API docs for an external/vendored repository into a project’s own documentation via from_git_clone

Under The Hood

Architecture The extension is organized around a clean pipeline: analysis.py walks Python source with astroid to yield typed ItemData records (independent of Sphinx), db.py defines a small Database protocol with an InMemoryDb implementation that stores and queries those items by full name, and render/ (base.py, rst_.py, myst_.py) turns database items into output text, decoupled entirely from Sphinx so the same analysis can drive the standalone autodoc2 CLI. The Sphinx integration itself lives in sphinx/extension.py, whose run_autodoc_package hashes source files to skip re-analysis on unchanged packages, clears and repopulates the database via autodoc2_db.remove/.add when something changed, then writes one output file per module only if its rendered content actually differs — avoiding unnecessary Sphinx rebuild triggers. Custom directives (autodoc2-docstring, autodoc2-summary, autodoc2-object) let users mix generated and hand-written documentation.

Tech Stack Core dependencies are astroid (>=2.7,<4, the static-analysis engine shared with pylint) for parsing, typing-extensions, and a tomli shim for Python <3.11; the optional sphinx extra requires sphinx>=4.0.0 and the cli extra pulls in typer[all] and rich for the standalone command-line tool. The package builds with flit_core and is distributed as sphinx-autodoc2 on PyPI while the importable module is autodoc2. Configuration is expressed as a dataclasses-based PackageConfig/Config pair that is introspected to auto-register Sphinx config values, and index pages are optionally rendered with jinja2 templates.

Code Quality The project ships a py.typed marker and runs mypy --strict (with narrow, justified ignore_missing_imports overrides for astroid/docutils/tomllib), plus ruff with an extensive rule set (bugbear, comprehensions, isort, simplify, pyupgrade, print-detection, and more) enforced via pre-commit. Tests live under tests/, using pytest with pytest-regressions for data-driven regression testing of analysis and rendering output (e.g. test_analyse_module.py, test_database.py, test_render.py), and CI runs the suite across Python 3.8-3.11 on Ubuntu and Windows plus a separate pre-commit lint job — a thorough, professionally maintained setup for a project of this size.

What Makes It Unique Unlike Sphinx’s built-in autodoc and the popular sphinx-autoapi alternative, sphinx-autodoc2 fully separates static analysis from rendering, so the same astroid-derived item database can drive Sphinx output, a standalone CLI, or in principle other renderers, none of which require the target package to be importable. It also specifically fixes known gaps in sphinx-autoapi around __all__ resolution and MyST docstring support, and adds correct source/line attribution to docstring warnings so Sphinx build warnings point at the right file and line rather than a synthesized template location.