---
id: sphinx-autodoc2
version: "0.5.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# sphinx-autodoc2 — Analyse a python project and create documentation for it.

License: permissive · Maintenance: active · Downloads: 305.1K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 305.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx api documentation generator, automatic python api docs, static code analysis documentation, sphinx extension autodoc, markdown rst docstring support, python package documentation tool, sphinx plugin api reference, static-analysis, api-documentation

[View on SkillFed](https://skillfed.io/packages/sphinx-autodoc2) · [View on PyPI](https://pypi.org/project/sphinx-autodoc2/)