sphinx-autoapi

sphinx-autoapi is a Sphinx extension, maintained by the Read the Docs project, that generates complete API documentation by statically parsing source code instead of importing and running it — unlike Sphinx’s traditional autodoc, which requires the documented package to be installed and importable. It supports Python (via astroid) as well as several other languages through separate parser backends, making it usable in CI/doc-build environments where the target codebase can’t be safely imported.

Once added to a Sphinx project’s conf.py and pointed at source directories via autoapi_dirs, it automatically generates an autoapi/ documentation tree and wires it into the project’s table of contents at build time.

What You Get

• A Sphinx extension (autoapi.extension) that auto-generates a complete API reference from source code without importing the project
• Static source parsing via astroid for Python, plus additional language parser backends for non-Python projects
• Configurable autoapi_dirs targeting and generation settings for controlling what gets documented and how
• Custom Sphinx directives and Jinja2-based templates for controlling the generated documentation’s structure and appearance
• Automatic wiring of the generated autoapi/ tree into the project’s top-level table of contents

Common Use Cases

• Building API docs in CI/Read the Docs environments where installing every runtime dependency of the documented package isn’t feasible or reliable
• Documenting a monorepo or library with complex/optional dependencies that would make import-based autodoc fragile or slow
• Generating consistent, always-up-to-date API reference pages as part of a normal sphinx-build run, without manually maintaining .rst stub files per module
• Documenting non-Python codebases within a Sphinx-based documentation site, via AutoAPI’s additional language backends

Under The Hood

Architecture The extension registers itself with Sphinx through src/autoapi/extension.py, which drives the build-time pipeline: _parser.py and _astroid_utils.py statically parse Python source into an AST via astroid (rather than importing it), _mapper.py and _objects.py build an in-memory object model of the discovered modules/classes/functions, and directives.py plus the templates/ directory (Jinja2) render that model into Sphinx-compatible .rst/documentation output; documenters.py and inheritance_diagrams.py add autodoc-compatible documenter classes and optional class-inheritance diagrams on top of the same object model.

Tech Stack It’s a Python package built on astroid (the static-analysis library also used by Pylint) for Python source parsing, Jinja2 for template rendering, and the Sphinx extension API itself as its integration surface; the project uses tox for multi-version/multi-Sphinx-version test matrices and ruff for formatting and linting.

Code Quality The repo has an extensive tests/ suite including test_integration.py (full end-to-end doc-build tests) and test_astroid_utils.py (unit tests of the AST-parsing layer), CI-gated tox runs, ruff format-enforced style, and towncrier-managed release notes requiring a news fragment per pull request — process discipline consistent with its role as Read the Docs’ own recommended documentation-generation extension.

API Design Day-to-day usage is minimal — add autoapi.extension to conf.py’s extensions list and set autoapi_dirs — while a documented configuration surface (templates, directive options, per-language settings) supports deep customization for projects with non-default doc-structure needs.