sphinx-autodoc2

What it is and what it does

sphinx-autodoc2 is a Sphinx extension that generates API documentation by analyzing Python code statically, without needing to import or install the target package. It parses source files directly using astroid, extracts docstrings (supporting both reStructuredText and Markdown), and respects `__all__` declarations to document only the public API. The analysis and rendering are decoupled, so you can use it outside Sphinx via a command-line tool.

The extension is optimized for development workflows through caching of analysis and rendering, and correctly handles Python typing constructs like `if TYPE_CHECKING` blocks. It supports mixed docstring formats within the same project and offers extensive configuration options. Three runtime dependencies (astroid, tomli, typing-extensions) keep the install footprint small, and the codebase uses type annotations and function-based rendering instead of complex templates.

Use it for:

• Generate API documentation for a Python package without installing it, useful for documenting packages from external sources or avoiding dependency conflicts.
• Migrate documentation from reStructuredText to Markdown docstrings incrementally while maintaining both formats in the same project.
• Build documentation in a CI/CD pipeline where caching speeds up rebuilds during development iterations.
• Document only the public API by leveraging `__all__` declarations, keeping generated docs focused and maintainable.
• Analyze and document packages outside of Sphinx using the standalone autodoc2 command-line tool.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

sphinx-autodoc2 generates API documentation for Python packages through static code analysis, without requiring package installation, and supports both reStructuredText and Markdown docstrings.

Yes. sphinx-autodoc2 is a solid choice if you need automatic API documentation for Python packages. It has low install friction, active maintenance, no known vulnerabilities, permissive licensing, and solves real pain points (static analysis, Markdown support, `__all__` handling) that motivated its creation. The 991-day gap since the last release is offset by recent repository activity, suggesting the project is stable rather than abandoned.

Install

sphinx-autodoc2 on PyPI

pip install sphinx-autodoc2

uv add sphinx-autodoc2

poetry add sphinx-autodoc2

Installing sphinx-autodoc2

Before you install

Low install friction with three lightweight runtime dependencies (astroid, tomli, typing-extensions). Active maintenance with recent commits; last release was 991 days ago but repository remains actively developed.

License in practice

Licensed under MIT (permissive), so you can use and modify the package freely in both open-source and proprietary projects with minimal restrictions.

Quickstart

pip install sphinx-autodoc2

# In conf.py:
extensions = ['sphinx_autodoc2']

# In your Sphinx documentation, reference the autodoc2 directive to generate API docs from your Python package.

Requires Python >= 3.8 and a working Sphinx documentation setup.

Verify before relying

• Whether the package handles complex type annotations (e.g., generics, unions) correctly in all Python versions it claims to support.
• Performance characteristics when analyzing very large packages or deeply nested module hierarchies.
• Compatibility with recent Sphinx versions beyond what the fact sheet indicates.

Package facts

Evidence: sphinx_autodoc2-0.5.0-py3-none-any.whl

Keywords: sphinx, autodoc, extension, documentation

Tags

More Sphinx packages