examples.rst

Examples

Configurations

While the configuration documentation contains all available options in detail, this page shows them in conjunction to provide different examples on how to display pydantic models and settings.

Default

This example shows the default out-of-the-box configuration of autodoc_pydantic. In contrast, it also shows how standard sphinx autodoc displays the same example code.

rendered output pydantic

rendered output sphinx

python

target.example_setting

reST

.. autopydantic_settings:: target.example_setting.ExampleSettings

Complete

This example represents a rendered output for which all features are enabled. It deviates from the default configuration above because it contains redundant information which is most likely not required. However, for demonstration purposes, this scenario covers all available display options for pydantic models/settings.

rendered output

reST

.. autopydantic_settings:: target.example_setting.ExampleSettings
   :noindex:
   :settings-show-config-member: True
   :validator-list-fields: True

python

target.example_setting

Fields only

In this scenario everything is hidden except actual pydantic fields. Validators and model/setting config is hidden.

rendered output

reST

.. autopydantic_settings:: target.example_setting.ExampleSettings
   :settings-show-json: False
   :settings-show-config-member: False
   :settings-show-config-summary: False
   :settings-show-validator-members: False
   :settings-show-validator-summary: False
   :field-list-validators: False

python

target.example_setting

Specifics

This section focuses rendered documentation examples of pydantic specific concepts such as root validators, required/optional fields or generic models.

Asterisk and root validators

This example highlights how asterisk (@validator('*')) and root validators (@root_validator) are represented. Since they validate all fields, their corresponding field reference is replaced with a simple all fields marker which hyperlinks to the related model itself.

rendered output

reST

.. autopydantic_model:: target.example_validators.ExampleValidators

python

target.example_validators

Note

By default the function signature of validators is replaced with hyperlinks to validated fields by autodoc_pydantic. You can disable this behaviour via validator-replace-signature <autodoc_pydantic_validator_replace_signature>.

Required/Optional fields

Pydantic has different ways to represent required or optional fields as described in the official documentation . The following example outlines all available combinations with the default autodoc_pydantic settings:

rendered output

reST

.. autopydantic_model:: target.example_required_optional_fields.RequiredOptionalField
   :member-order: bysource
   :model-summary-list-order: bysource

python

target.example_required_optional_fields

Swap field name with alias

It is possible to completely replace the field name with the provided field alias when field-swap-name-and-alias <autodoc_pydantic_field_swap_name_and_alias> is enabled:

rendered output with swap

rendered output without swap

reST

.. autopydantic_model:: target.example_swap_name_with_alias.SwapFieldWithAlias
   :field-swap-name-and-alias:
   :validator-list-fields:

python

target.example_swap_name_with_alias

Generic Models

Generic pydantic models can be documented just as normal models, too. The following example is borrowed from the official pydantic documentation :

rendered output

target.example_generics

reST

.. automodule:: target.example_generics
   :members:

python

target.example_generics