Installation

autodoc_pydantic is a sphinx extension and works well with pydantic >= 1.5.0 and sphinx >= 3.5.0.

Note

Pydantic v2 is supported by autodoc_pydantic >= 2.0.0 while pydantic v1 remains functional via autodoc_pydantic < 2.0.0. By default, your dependency resolver automatically selects the correct autodoc_pydantic version based on the given pydantic version. However, it is best practice to manually pin your dependency ranges accordingly.

For more information regarding the migration from v1 to v2, please refer to the FAQ.

1. Install with pip

autodoc_pydantic needs to be installed just like any other python package into your documentation building environment:

pip install autodoc_pydantic

Warning

If you wish to use the model-erdantic-figure feature to visualize ERD, you will need to install graphviz first, then install autodoc_pydantic with the erdantic option:

pip install autodoc_pydantic[erdantic]

2. Enable extension

Once installed, you’ll need to enable it within sphinx’ conf.py:

extensions = ['sphinxcontrib.autodoc_pydantic']

3. Configuration

autodoc_pydantic can be completely customized to meet your individual requirements. As an example, to display the collapsible JSON schema for pydantic models but to hide them for pydantic settings, add the following to sphinx’ conf.py:

autodoc_pydantic_model_show_json = True
autodoc_pydantic_settings_show_json = False

All available options are covered in detail with examples in the Configuration documentation.

The default configuration already takes effect as soon as you enable autodoc_pydantic. More concretely, sphinx’ autodoc directives like automodule will already use the newly added pydantic documenters. To explicitly use the autodoc_pydantic directives, please visit the Usage documentation.