sphinxcontrib-pydantic 0.4.0

A simple integration between autodoc and Pydantic in your Sphinx documentation.

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

Option	Default	Description
model_show_json	False	Show JSON schema for the model
model_show_field_summary	True	Show summary table of fields
model_show_validator_summary	True	Show summary table of validators
model_show_members	True	Show individual field/validator documentation (directives only)
model_signature_prefix	"model"	Prefix shown before model name (directives only)
model_hide_paramlist	True	Hide __init__ parameter list

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

Option	Default	Description
field_show_alias	True	Show field aliases
field_show_default	True	Show default values
field_show_required	True	Show required status
field_show_constraints	True	Show field constraints (e.g., min_length)

Validator Options

Option	Default	Description
validator_list_fields	True	List fields affected by each validator

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.

Option	Default	Description
settings_show_json	False	Show JSON schema for the setting
settings_show_field_summary	True	Show summary table of fields
settings_show_validator_summary	True	Show summary table of validators
settings_show_members	True	Show individual field/validator documentation (directives only)
settings_signature_prefix	"settings"	Prefix shown before setting name (directives only)
settings_hide_paramlist	True	Hide __init__ parameter list

Interoperability Options

Option	Default	Description
resolve_legacy_inventories	False	Resolve cross-references into objects.inv files produced by the legacy autodoc_pydantic extension

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"