autodoc-pydantic

2.2.0 · active · verified Wed Apr 15

autodoc-pydantic is a Sphinx extension that seamlessly integrates Pydantic models into Sphinx documentation. It automatically generates documentation for model fields, validators, and configurations, enhancing the standard Sphinx autodoc capabilities for data models. The current version is 2.2.0, with an active development cycle and regular updates.

Common errors

```
ModuleNotFoundError: No module named 'autodoc_pydantic'
```
cause This error occurs when the 'autodoc_pydantic' package is not installed in the Python environment.

fix Install the package using pip: 'pip install autodoc_pydantic'.
```
AttributeError: type object 'Foo' has no attribute 'Config'
```
cause This error occurs when autodoc_pydantic misinterprets a non-Pydantic class as a Pydantic model, leading it to expect a 'Config' attribute that doesn't exist.

fix Ensure that only classes inheriting from 'pydantic.BaseModel' are processed by autodoc_pydantic, and update to version 1.7.2 or later where this issue is resolved.
```
AttributeError: module 'pydantic' has no attribute 'Field'
```
cause This error occurs when there's a version mismatch between Pydantic and autodoc_pydantic, leading to compatibility issues.

fix Ensure that both Pydantic and autodoc_pydantic are updated to compatible versions; for Pydantic v2, use autodoc_pydantic >= 2.0.0.
```
Unknown directive type
```
cause The autodoc-pydantic Sphinx extension has not been properly enabled in your Sphinx project's configuration.

fix Add 'sphinxcontrib.autodoc_pydantic' to the 'extensions' list in your `conf.py` file.
```
WARNING: py:obj reference target not found: typing.Annotated[...]
```
cause Sphinx's autodoc, which autodoc-pydantic relies on, struggles to resolve complex type hints like `typing.Annotated` within Pydantic models, possibly due to version incompatibilities or inherent limitations in Sphinx's type resolution.

fix Ensure Sphinx, Pydantic, and autodoc-pydantic are updated to compatible versions. Consider simplifying complex type hints if possible, or investigate specific Sphinx configuration options for handling annotations.

Warnings

breaking Version 2.0.0 introduced significant breaking changes in configuration options to align with Pydantic v2 and refine features. Many `autodoc_pydantic_*` settings were renamed, removed, or had their default behavior altered.
Fix: Consult the official migration guide for autodoc-pydantic v2.0.0. For example, `autodoc_pydantic_model_show_config` was renamed to `autodoc_pydantic_model_show_json`, and `autodoc_pydantic_model_show_config_summary` was removed.
gotcha For autodoc-pydantic's directives to function correctly, `sphinx.ext.autodoc` must be present in your `extensions` list in `conf.py`. Without it, Pydantic model documentation will fail or appear incomplete.
Fix: Ensure your `conf.py` includes `sphinx.ext.autodoc`, for instance: `extensions = ['sphinx.ext.autodoc', 'autodoc_pydantic']`.
gotcha autodoc-pydantic automatically uses the `description` argument of Pydantic's `Field` as the field's docstring. This might lead to redundant or undesired output if you're also providing explicit docstrings or using other methods.
Fix: If you wish to control this behavior, set `autodoc_pydantic_field_show_description = False` in your `conf.py` or explore other `autodoc_pydantic_field_show_...` options to fine-tune how field descriptions are presented.
gotcha When using Pydantic v1 vs. Pydantic v2, autodoc-pydantic adapts its behavior. If you switch Pydantic versions, especially upgrading from v1 to v2, your documentation output might change or require configuration adjustments.
Fix: Ensure your autodoc-pydantic version is compatible with your installed Pydantic version (v2.0.0+ is recommended for Pydantic v2). Review your autodoc-pydantic configurations after a Pydantic version change, as some displays or features might have altered.

Install

pip install autodoc-pydantic sphinx pydantic Install with core dependencies

Imports

autodoc_pydantic (Sphinx Extension)
wrong:
```
extensions = ['autodoc_pydantic.plugin']
```
correct:
```
# In conf.py, inside the project's source directory:
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon', # Or other docstring parsing extensions
    'autodoc_pydantic'
]
```
autodoc-pydantic is enabled by adding its module name as a string to the `extensions` list in Sphinx's `conf.py`. There are no direct Python symbols usually imported by end-users.

Quickstart

To integrate autodoc-pydantic, first create a Sphinx project. Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to your `extensions` list in `conf.py`. Define your Pydantic models in Python modules. Then, use Sphinx's `automodule` combined with autodoc-pydantic's specific directives (e.g., `autodoc_pydantic_model`, `autodoc_pydantic_field`) in your documentation files to generate detailed API documentation for your Pydantic models.

# 1. Install dependencies: pip install autodoc-pydantic sphinx pydantic

# 2. Initialize a Sphinx project (e.g., using 'sphinx-quickstart')

# 3. Modify conf.py:
#    Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to the extensions list.
#    Example conf.py snippet:
#    extensions = [
#        'sphinx.ext.autodoc',
#        'sphinx.ext.napoleon', # For Google/NumPy style docstrings
#        'autodoc_pydantic'
#    ]

# 4. Create a Python file (e.g., 'my_models.py'):
#    from pydantic import BaseModel, Field
#
#    class User(BaseModel):
#        """Represents a user in the system."""
#        name: str = Field(..., description="The user's full name")
#        age: int = Field(default=18, ge=0, description="The user's age")

# 5. Create an RST or Markdown file (e.g., 'models.rst'):
#    .. automodule:: my_models
#       :members:
#
#    .. autodoc_pydantic_model:: my_models.User
#       :model-show-json: False
#       :model-show-config-summary: False

# 6. Build your documentation: make html (or sphinx-build -b html . _build)

view raw JSON →