Usage

Autodoc Sphinx

autodoc_pydantic integrates seamlessly with sphinx’ autodoc. Therefore, you might not need to modify your code at all when using automodule.

automodule

In this case, autodoc passes the documentation of all pydantic objects directly to autodoc_pydantic:

.. automodule:: target.example_setting
   :members:

Autodoc Pydantic

If you don’t want to rely on the automodule directive, autodoc_pydantic adds custom directives for pydantic models, settings, fields, validators and config class.

To completely customize a specific directive, you can use all available directive options, as explained in detail in the Configuration section.

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.example_model.ExampleModel

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.example_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.example_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.example_setting.ExampleSettings.check_max_length_ten

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

Options

autopydantic_config

Very rarely, you may want to document a pydantic config class without the corresponding pydantic model/setting. However, technically it’s possible since the autopydantic_config directive is used by the autopydantic_model and autopydantic_settings.

.. autopydantic_config:: target.example_setting.ExampleSettings.Config

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

Options