$ show readthedocs/sphinx-autoapi
Sphinx AutoAPI is a Sphinx extension that automatically generates API documentation by statically analyzing Python source code using the astroid library, without importing or executing the documented code. It reads Python files and .pyi stubs, builds an internal object model (modules, classes, functions, etc.), applies configurable filtering options (e.g., private members, inherited members), and renders the documentation as RST via Jinja templates. The extension also provides autodoc-style directives (e.g., autoapifunction, autoapimethod) that allow manual documentation entries backed by the same static analysis, and supports inheritance diagrams, type annotation rendering, PEP-695 type parameters, overloaded signatures, and integration with Sphinx's viewcode. Its architecture separates parsing (astroid-based), mapping (object creation and option evaluation), and output (template rendering), making the core logic reusable in other static analysis tools.
The LLM identified 2 files worth highlighting for reuse:
A self-contained utility module that provides functions for extracting information from astroid AST nodes: resolving imports to fully qualified names, extracting argument annotations (including type comments, PEP-604 unions, PEP-695 type params), detecting decorators (property, overload), resolving inheritance, and formatting annotations. It depends only on astroid, builtins, itertools, re, and typing. This module can be extracted into a separate library for any project that needs to statically analyze Python source code (e.g., code generation, linting, or documentation tools). It demonstrates deep understanding of astroid's API and handles many edge cases gracefully.
The parser module that walks astroid nodes and converts them into a dictionary representation suitable for documentation generation. It handles all major Python constructs: modules, packages, classes, functions, methods, properties, data attributes, assignment annotations, overloads, type aliases, NamedTuples, and constructors. It resolves inherited members and docstrings using astroid's tree traversal. While it depends on _astroid_utils and Sphinx's docstring preparation utilities, the core parsing logic is clean and modular, making it adaptable for other static analysis tasks with minimal modification.