{"id":6528,"library":"autodoc-pydantic","title":"autodoc-pydantic","description":"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.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/mansenfranzen/autodoc_pydantic","tags":["sphinx","pydantic","documentation","autodoc","api-documentation","data-models"],"install":[{"cmd":"pip install autodoc-pydantic sphinx pydantic","lang":"bash","label":"Install with core dependencies"}],"dependencies":[{"reason":"Core documentation generation framework, autodoc-pydantic is a Sphinx extension.","package":"sphinx","optional":false},{"reason":"Library for which this extension provides documentation support. Works with both Pydantic v1 and v2, but has different internal handling.","package":"pydantic","optional":false}],"imports":[{"note":"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.","wrong":"extensions = ['autodoc_pydantic.plugin']","symbol":"autodoc_pydantic (Sphinx Extension)","correct":"# In conf.py, inside the project's source directory:\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon', # Or other docstring parsing extensions\n    'autodoc_pydantic'\n]"}],"quickstart":{"code":"# 1. Install dependencies: pip install autodoc-pydantic sphinx pydantic\n\n# 2. Initialize a Sphinx project (e.g., using 'sphinx-quickstart')\n\n# 3. Modify conf.py:\n#    Add 'sphinx.ext.autodoc' and 'autodoc_pydantic' to the extensions list.\n#    Example conf.py snippet:\n#    extensions = [\n#        'sphinx.ext.autodoc',\n#        'sphinx.ext.napoleon', # For Google/NumPy style docstrings\n#        'autodoc_pydantic'\n#    ]\n\n# 4. Create a Python file (e.g., 'my_models.py'):\n#    from pydantic import BaseModel, Field\n#\n#    class User(BaseModel):\n#        \"\"\"Represents a user in the system.\"\"\"\n#        name: str = Field(..., description=\"The user's full name\")\n#        age: int = Field(default=18, ge=0, description=\"The user's age\")\n\n# 5. Create an RST or Markdown file (e.g., 'models.rst'):\n#    .. automodule:: my_models\n#       :members:\n#\n#    .. autodoc_pydantic_model:: my_models.User\n#       :model-show-json: False\n#       :model-show-config-summary: False\n\n# 6. Build your documentation: make html (or sphinx-build -b html . _build)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your `conf.py` includes `sphinx.ext.autodoc`, for instance: `extensions = ['sphinx.ext.autodoc', 'autodoc_pydantic']`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All (during Pydantic version transitions)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install autodoc_pydantic'.","cause":"This error occurs when the 'autodoc_pydantic' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'autodoc_pydantic'"},{"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.","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.","error":"AttributeError: type object 'Foo' has no attribute 'Config'"},{"fix":"Ensure that both Pydantic and autodoc_pydantic are updated to compatible versions; for Pydantic v2, use autodoc_pydantic >= 2.0.0.","cause":"This error occurs when there's a version mismatch between Pydantic and autodoc_pydantic, leading to compatibility issues.","error":"AttributeError: module 'pydantic' has no attribute 'Field'"},{"fix":"Add 'sphinxcontrib.autodoc_pydantic' to the 'extensions' list in your `conf.py` file.","cause":"The autodoc-pydantic Sphinx extension has not been properly enabled in your Sphinx project's configuration.","error":"Unknown directive type"},{"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.","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.","error":"WARNING: py:obj reference target not found: typing.Annotated[...]"}]}