sphinx-autodoc2
is a Sphinx extension that automatically generates API documentation for your Python packages.
Static analysis of Python code
: There is no need to install your package to generate the documentation, and sphinx-autodoc2
will correctly handle if TYPE_CHECKING
blocks and other typing only features.
: You can even document packages from outside the project (via git clone
)!
Optimized for rebuilds
: Analysis of packages and file rendering are cached, so you can use sphinx-autodoc2
in your development workflow.
Support for __all__
: sphinx-autodoc2
can follow __all__
variable, to only document the public API.
Support for both rst
and md
docstrings
: sphinx-autodoc2
supports both rst
and md
(MyST) docstrings, which can be mixed within the same project.
Highly configurable
: sphinx-autodoc2
is highly configurable, with many options to control the analysis and output of the documentation.
Decoupled analysis and rendering
: The analysis and rendering of the documentation are decoupled, and not dependent on Sphinx.
: This means that you can use sphinx-autodoc2
to generate documentation outside of Sphinx (see the autodoc2
command line tool).
See the documentation for more information!
I wanted an extension with the following goals:
if TYPE_CHECKING
were handled correctlyrst
to md
, i.e. mixing docstrings__all__
variableI am not looking to support other languages tha Python (at least for now).
sphinx-autoapi was a good candidate, but it had a few issues:
__all__
very well: https://github.com/readthedocs/sphinx-autoapi/issues/358I've use a lot of their code, for the astroid
static analysis, but I've made a number of "improvements":
a | b
annotations inferencefunctools.singledispatch
and their registers__all__
:canonical:
to py
directiveslist-table
, instead of auto-summary
directiveAll configuration is mainly in pyproject.toml
.
Use tox to run the tests.
pipx install tox
tox -av
Use pre-commit to run the linters and formatters.
pipx install pre-commit
pre-commit run --all-files
# pre-commit install
flit is used to build the package.
pipx install flit
flit build