sphinx-autodoc-fern

sphinx-autodoc-fern is a Sphinx extension that automatically generates API documentation for your Python packages with Fern documentation format support.

This is a fork of sphinx-autodoc2 that adds powerful Fern documentation generation capabilities.

🆕 New Fern Features

• Fern-compatible Markdown output - Generate documentation that works seamlessly with Fern
• Enhanced parameter formatting - Uses Fern's ParamField components for better API documentation
• Smart callout handling - Automatically converts NOTE: and WARNING: to Fern components
• Beautiful tables - Improved formatting for classes, functions, and module contents

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-autodoc-fern is highly configurable, with many options to control the analysis and output of the documentation.

Fern Documentation Format Support

: Generate beautiful Fern-compatible documentation with enhanced formatting for parameters, callouts, and API references.

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-autodoc-fern to generate documentation outside of Sphinx (see the autodoc2 command line tool).

🚀 Quick Start with Fern

pip install sphinx-autodoc-fern

To use the Fern renderer:

from autodoc2.render.fern_ import FernRenderer

renderer = FernRenderer()
# Generate Fern-compatible documentation

Or use with the CLI:

autodoc2 --renderer fern your_package/

Acknowledgments

This project is a fork of the excellent sphinx-autodoc2 by Chris Sewell. All credit for the core functionality goes to the original project.

Design and comparison to sphinx-autoapi

The original sphinx-autodoc2 was created 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:

• It does not support MyST docstrings: readthedocs/sphinx-autoapi#287
• It does not support the __all__ very well: readthedocs/sphinx-autoapi#358
• The analysis and rendering are coupled, making it difficult to test, modify and use outside of Sphinx

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