Skip to content

A Sphinx extension that automatically generates API documentation for your Python packages.

License

Notifications You must be signed in to change notification settings

sphinx-extensions2/sphinx-autodoc2

Repository files navigation

sphinx-autodoc2

sphinx-autodoc2 is a Sphinx extension that automatically generates API documentation for your Python packages.

GitHub Repo stars PyPI

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!

Design and comparison to sphinx-autoapi

I wanted an extension with the following goals:

  • Static analysis of Python code, so things like if TYPE_CHECKING were handled correctly
  • Support for MyST docstrings (see executablebooks/MyST-Parser#228)
    • Also support for transitioning from rst to md, i.e. mixing docstrings
  • Make it simple and minimise the amount of configuration and rebuilds necessary
  • Support for building public API via __all__ variable

I 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:

I've use a lot of their code, for the astroid static analysis, but I've made a number of "improvements":

  • separating concerns: analysis and template writing
  • type annotations for code base
  • fixed a | b annotations inference
  • added analysis of functools.singledispatch and their registers
  • handling of __all__
  • docstrings (and summaries) are now parsed with the correct source/line, i.e. warnings point to the correct location in the source file
  • added :canonical: to py directives
  • Moved away from using jinja templates, to using python functions
    • IMO the templates were too complex and hard to read, plus they do not benefit from any form of type checking, linting, etc.
    • uses list-table, instead of auto-summary directive

Development

All 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

About

A Sphinx extension that automatically generates API documentation for your Python packages.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages