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:
- pydantic settings AutoModuleSettings[source]
Document your project settings very conveniently. Applies like wise to pydantic models.
Show JSON schema
{ "title": "AutoModuleSettings", "description": "Document your project settings very conveniently. Applies like wise\nto pydantic models.", "type": "object", "properties": { "field_without_default": { "title": "Field Without Default", "env_names": "{'foo_field_without_default'}", "type": "string" }, "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": "BarFoo", "env_names": "{'barfoo'}", "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" } }, "required": [ "field_without_default" ], "additionalProperties": false }
- Config:
allow_mutation: bool = True
env_prefix: str = foo_
- Fields:
field_plain_with_validator (int)
field_with_constraints_and_description (int)
field_with_validator_and_alias (str)
field_without_default (str)
- Validators:
check_max_length_ten
»field_plain_with_validator
check_max_length_ten
»field_with_validator_and_alias
- 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
- field field_without_default: str [Required]
Shows the [Required] marker in the signature.
- validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator[source]
Show corresponding field with link/anchor.
from pydantic import BaseSettings, validator, Field
class AutoModuleSettings(BaseSettings):
"""Document your project settings very conveniently. Applies like wise
to pydantic models.
"""
field_without_default: str
"""Shows the *[Required]* marker in the signature."""
field_plain_with_validator: int = 100
"""Show standard field with type annotation."""
field_with_validator_and_alias: str = Field("FooBar",
alias="BarFoo",
env="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 len(v) >= 10:
raise ValueError("No more than 10 characters allowed")
return v
class Config:
env_prefix = "foo_"
allow_mutation = True
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
Document your project settings very conveniently. |
|
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 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.ExampleModel
- pydantic model ExampleModel[source]
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_
- Fields:
field_plain_with_validator (int)
field_with_constraints_and_description (int)
field_with_validator_and_alias (str)
- Validators:
check_max_length_ten
»field_plain_with_validator
check_max_length_ten
»field_with_validator_and_alias
- 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_plain_with_validator, field_with_validator_and_alias[source]
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 len(v) >= 10:
raise ValueError("No more than 10 characters allowed")
return v
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.usage_setting.ExampleSettings
- pydantic settings ExampleSettings[source]
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_without_default": { "title": "Field Without Default", "env_names": "{'foo_field_without_default'}", "type": "string" }, "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": "BarFoo", "env_names": "{'barfoo'}", "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" } }, "required": [ "field_without_default" ], "additionalProperties": false }
- Config:
allow_mutation: bool = True
env_prefix: str = foo_
- Fields:
field_plain_with_validator (int)
field_with_constraints_and_description (int)
field_with_validator_and_alias (str)
field_without_default (str)
- Validators:
check_max_length_ten
»field_plain_with_validator
check_max_length_ten
»field_with_validator_and_alias
- 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
- field field_without_default: str [Required]
Shows the [Required] marker in the signature.
- validator check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator[source]
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_without_default: str
"""Shows the *[Required]* marker in the signature."""
field_plain_with_validator: int = 100
"""Show standard field with type annotation."""
field_with_validator_and_alias: str = Field("FooBar",
alias="BarFoo",
env="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 len(v) >= 10:
raise ValueError("No more than 10 characters allowed")
return v
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.usage_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_without_default: str
"""Shows the *[Required]* marker in the signature."""
field_plain_with_validator: int = 100
"""Show standard field with type annotation."""
field_with_validator_and_alias: str = Field("FooBar",
alias="BarFoo",
env="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 len(v) >= 10:
raise ValueError("No more than 10 characters allowed")
return v
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
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
- validator ExampleSettings.check_max_length_ten » field_with_validator_and_alias, field_plain_with_validator[source]
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_without_default: str
"""Shows the *[Required]* marker in the signature."""
field_plain_with_validator: int = 100
"""Show standard field with type annotation."""
field_with_validator_and_alias: str = Field("FooBar",
alias="BarFoo",
env="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 len(v) >= 10:
raise ValueError("No more than 10 characters allowed")
return v
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
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.usage_setting.ExampleSettings.Config
- model 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_without_default: str
"""Shows the *[Required]* marker in the signature."""
field_plain_with_validator: int = 100
"""Show standard field with type annotation."""
field_with_validator_and_alias: str = Field("FooBar",
alias="BarFoo",
env="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 len(v) >= 10:
raise ValueError("No more than 10 characters allowed")
return v
class Config:
env_prefix = "foo_"
allow_mutation = True
To overwrite global defaults, the following directive options can be supplied:
- Options: