Usage

autodoc_pydantic integrates seamlessly with sphinx’ default auto-documentation directives such as automodule and autosummary.

automodule

The automodule directive of the sphinx.ext.autodoc extension documents the content of an entire python module. All pydantic objects that are encountered will be documented by autodoc_pydantic’s specialized auto-documenters:

.. automodule:: target.usage_automodule
   :members:

autosummary

The autosummary directive of the sphinx.ext.autosummary extension generates a table of references and short descriptions for a list of python objects. Additionally, it can automatically generate individual documentation pages (called stubs) for each entry. This makes it fairly easy to sufficiently document several python objects at once:

.. currentmodule:: target.usage_autosummary

.. autosummary::
   :toctree: _autosummary

   AutoSummaryModel
   AutoSummarySettings

Please note, this example generates the autosummary table with hyperlinks to the corresponding stub pages.

Hint

To enable automatic stub generation, remember the following steps:

  • Add the sphinx.ext.autosummary extension in conf.py.

  • Set autosummary_generate = True in conf.py.

  • Add :toctree: option to the autosummary directive.

For more information, please visit the official documentation of sphinx.ext.autosummary.

Warning

The generated stub pages do not use the standard autosummary templates (e.g. the class template which lists all methods and attributes). As of sphinx version 3.5.4, this is not possible because autosummary does not support custom autodocumenters provided by extensions such as autodoc_pydantic (see sphinx issue 6264). Instead, autodoc_pydantic’s autodocumenters are used to render the object’s documentation in the generated stub pages of autosummary.

autopydantic

You may want to document pydantic objects explicitly. This is possible via the specialized directives provided by autodoc_pydantic:

autopydantic_model

In comparison the automodule, you don’t need to add directive options like :members: to show all members. Instead, autodoc_pydantic supplies sensible default settings.

.. autopydantic_model:: target.usage_model.ExampleSettings

To overwrite global defaults, the following directive options can be supplied:

Options:

autopydantic_settings

Documenting pydantic models behaves exactly like autopydantic_model.

.. autopydantic_settings:: target.usage_setting.ExampleSettings

To overwrite global defaults, the following directive options can be supplied:

Options:

autopydantic_field

In some rare cases, you may want to document individual pydantic fields. In most cases, pydantic fields are documented along with its corresponding pydantic model/setting.

.. autopydantic_field:: target.usage_setting.ExampleSettings.field_with_constraints_and_description

To overwrite global defaults, the following directive options can be supplied:

Options:

autopydantic_validator

As with pydantic validators, one usually does not document validators separately from its corresponding pydantic model/settings but it is still possible.

.. autopydantic_validator:: target.usage_setting.ExampleSettings.check_max_length_ten

To overwrite global defaults, the following directive options can be supplied:

Options: