Usage¶

autodoc_pydantic integrates seamlessly with sphinx’ auto-documentation utilities. You might not need to modify your code at all when using autosummary and automodule directives.

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.example_autosummary

.. autosummary::
   :toctree: _autosummary

   AutoSummaryModel
   AutoSummarySettings

`AutoSummaryModel`	Document your project settings very conveniently.
`AutoSummarySettings`	Some settings with pydantic.

from pydantic import BaseModel, Field, validator, BaseSettings


class AutoSummaryModel(BaseModel):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 200
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True


class AutoSummarySettings(BaseSettings):
    """Some settings with pydantic."""

    field: int = 1
    """Doc field"""

Please note, this example generates the autosummary table and the corresponding stub pages which are referenced when clicking on the table items.

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.

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.example_setting
   :members:

pydantic settings target.example_setting.ExampleSettings

Document your project settings very conveniently. Applies like wise to pydantic models.

Show JSON schema

{
   "title": "ExampleSettings",
   "description": "Document your project settings very conveniently. Applies like wise\nto pydantic models.",
   "type": "object",
   "properties": {
      "field_plain_with_validator": {
         "title": "Field Plain With Validator",
         "default": 100,
         "env_names": [
            "foo_field_plain_with_validator"
         ],
         "type": "integer"
      },
      "BarFoo": {
         "title": "Barfoo",
         "default": "FooBar",
         "env_names": [
            "foo_field_with_validator_and_alias"
         ],
         "type": "string"
      },
      "field_with_constraints_and_description": {
         "title": "Field With Constraints And Description",
         "description": "Shows constraints within doc string.",
         "default": 5,
         "minimum": 0,
         "maximum": 100,
         "env_names": [
            "foo_field_with_constraints_and_description"
         ],
         "type": "integer"
      }
   },
   "additionalProperties": false
}

Config

allow_mutation: bool = True
env_prefix: str = foo_

Validators

field field_plain_with_validator: int = 100

Show standard field with type annotation.

Validated by

check_max_length_ten

field field_with_constraints_and_description: int = 5

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

field field_with_validator_and_alias: str = 'FooBar' (alias 'BarFoo')

Shows corresponding validator with link/anchor.

Validated by

check_max_length_ten

validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator: Show corresponding field with link/anchor.

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

autopydantic¶

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

autopydantic_model
autopydantic_settings
autopydantic_field
autopydantic_validator
autopydantic_config

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

pydantic model target.example_model.ExampleModel

Document your project settings very conveniently. Applies like wise to pydantic models.

Show JSON schema

{
   "title": "ExampleModel",
   "description": "Document your project settings very conveniently. Applies like wise\nto pydantic models.",
   "type": "object",
   "properties": {
      "field_plain_with_validator": {
         "title": "Field Plain With Validator",
         "default": 100,
         "type": "integer"
      },
      "BarFoo": {
         "title": "Barfoo",
         "default": "FooBar",
         "type": "string"
      },
      "field_with_constraints_and_description": {
         "title": "Field With Constraints And Description",
         "description": "Shows constraints within doc string.",
         "default": 5,
         "minimum": 0,
         "maximum": 100,
         "type": "integer"
      }
   }
}

Config

allow_mutation: bool = True
env_prefix: str = foo_

Validators

check_max_length_ten » field_with_validator_and_alias
check_max_length_ten » field_plain_with_validator

field field_plain_with_validator: int = 100

Show standard field with type annotation.

Validated by

check_max_length_ten

field field_with_constraints_and_description: int = 5

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

field field_with_validator_and_alias: str = 'FooBar' (alias 'BarFoo')

Shows corresponding validator with link/anchor.

Validated by

check_max_length_ten

validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator: Show corresponding field with link/anchor.

from pydantic import BaseModel, validator, Field


class ExampleModel(BaseModel):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

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

pydantic settings target.example_setting.ExampleSettings

Document your project settings very conveniently. Applies like wise to pydantic models.

Show JSON schema

{
   "title": "ExampleSettings",
   "description": "Document your project settings very conveniently. Applies like wise\nto pydantic models.",
   "type": "object",
   "properties": {
      "field_plain_with_validator": {
         "title": "Field Plain With Validator",
         "default": 100,
         "env_names": [
            "foo_field_plain_with_validator"
         ],
         "type": "integer"
      },
      "BarFoo": {
         "title": "Barfoo",
         "default": "FooBar",
         "env_names": [
            "foo_field_with_validator_and_alias"
         ],
         "type": "string"
      },
      "field_with_constraints_and_description": {
         "title": "Field With Constraints And Description",
         "description": "Shows constraints within doc string.",
         "default": 5,
         "minimum": 0,
         "maximum": 100,
         "env_names": [
            "foo_field_with_constraints_and_description"
         ],
         "type": "integer"
      }
   },
   "additionalProperties": false
}

Config

allow_mutation: bool = True
env_prefix: str = foo_

Validators

field field_plain_with_validator: int = 100

Show standard field with type annotation.

Validated by

check_max_length_ten

field field_with_constraints_and_description: int = 5

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

field field_with_validator_and_alias: str = 'FooBar' (alias 'BarFoo')

Shows corresponding validator with link/anchor.

Validated by

check_max_length_ten

validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator: Show corresponding field with link/anchor.

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

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

field ExampleSettings.field_with_constraints_and_description: int = 5

Shows constraints within doc string.

Constraints

minimum = 0
maximum = 100

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

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

validator ExampleSettings.check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator: Show corresponding field with link/anchor.

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

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

model target.example_setting.ExampleSettings.Config

allow_mutation = True

env_prefix = 'foo_'

from pydantic import BaseSettings, validator, Field


class ExampleSettings(BaseSettings):
    """Document your project settings very conveniently. Applies like wise
    to pydantic models.

    """

    field_plain_with_validator: int = 100
    """Show standard field with type annotation."""

    field_with_validator_and_alias: str = Field("FooBar", alias="BarFoo")
    """Shows corresponding validator with link/anchor."""

    field_with_constraints_and_description: int = Field(
        default=5,
        ge=0,
        le=100,
        description="Shows constraints within doc string."
    )

    @validator("field_with_validator_and_alias", "field_plain_with_validator")
    def check_max_length_ten(cls, v):
        """Show corresponding field with link/anchor.

        """

        if not len(v) < 10:
            raise ValueError("No more than 10 characters allowed")

    class Config:
        env_prefix = "foo_"
        allow_mutation = True

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

Options