sphinxcontrib-pydantic

A Sphinx extension for documenting Pydantic models in your documentation.

This project was inspired by autodoc_pydantic, which I have been using for years but has gone unmaintained and is now incompatible with Sphinx 9.0+. Unlike its predecessor, sphinxcontrib-pydantic focuses exclusively on modern versions: Pydantic v2+ and Sphinx 9.0+ (Python 3.11+).

This project was vibe-coded using Claude Code (Opus 4.5); using autodoc_pydantic as inspiration as well as the source code of sphinx and pydantic as documentation.

Installation

pip install sphinxcontrib-pydantic

Configuration

Enable the extension in your conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinxcontrib.pydantic",
]

Usage

With autodoc

The extension integrates with sphinx.ext.autodoc. Simply use automodule or autoclass:

.. automodule:: mypackage.models
   :members:

Pydantic models are automatically detected and documented with field summaries and validators.

With autosummary

For larger projects, use autosummary with a custom template:

.. currentmodule:: mypackage.models

.. autosummary::
   :toctree: generated/api
   :template: autosummary/models.rst

   UserConfig
   DatabaseConfig

Create _templates/autosummary/models.rst:

{{ fullname | escape | underline }}

.. currentmodule:: {{ module }}

.. pydantic-model:: {{ fullname }}
   :inherited-members: BaseModel

Standalone directives

Document models directly with the pydantic-model directive:

.. pydantic-model:: mypackage.models.UserConfig
   :show-field-summary:
   :show-validator-summary:

For Pydantic settings:

.. pydantic-settings:: mypackage.settings.AppSettings
   :show-field-summary:

Configuration Options

All options use the sphinxcontrib_pydantic_ prefix in conf.py, e.g. sphinxcontrib_pydantic_model_show_json.

Model Options

Note: The signature_prefix and show_members options only affect directive-based documentation (pydantic-model, pydantic-settings). When using autodoc (autoclass, automodule), the standard "class" prefix is used and members are documented via autodoc's member processing.

Field Options

Validator Options

Settings Options

Settings options mirror model options with settings_ prefix (e.g., sphinxcontrib_pydantic_settings_show_json). They default to the same values as their model counterparts.

Interoperability Options

autodoc_pydantic documents Pydantic objects under custom Python-domain object types (py:pydantic_model, py:pydantic_field, ...) rather than the stock py:class. A project built with this extension does not know those object types, so a cross-reference (e.g. via intersphinx) into a project still documented with autodoc_pydantic cannot resolve and a nitpicky build fails. Enable this option to register those object types (object types only, no directives) so such references resolve:

# conf.py
extensions = ["sphinx.ext.intersphinx", "sphinxcontrib.pydantic"]
intersphinx_mapping = {"legacy": ("https://legacy.example/docs/", None)}
sphinxcontrib_pydantic_resolve_legacy_inventories = True

Example Configuration

# conf.py
sphinxcontrib_pydantic_model_show_json = True
sphinxcontrib_pydantic_model_show_field_summary = True
sphinxcontrib_pydantic_field_show_constraints = True
sphinxcontrib_pydantic_settings_signature_prefix = "config"