Skip to content

Latest commit

 

History

History
653 lines (479 loc) · 23 KB

configuration.rst

File metadata and controls

653 lines (479 loc) · 23 KB
Raw

Configuration

One major strength of autodoc_pydantic is that every feature is completely configurable to allow maximum customization. There are two ways to configure how pydantic objects are displayed:

  • conf.py: Globally define the default configuration via conf.py which takes effect for all pydantic objects like:

    autodoc_pydantic_model_show_json = True
autodoc_pydantic_model_show_config_summary = False

  • directive: Locally define specific configurations via directive options. This overrides global configuration settings:

    .. autopydantic_model:: module.Model
   :model-show-json: True
   :model-show-config-summary: False

Note

The following sections describe all available configurations in separation. Each configuration is activated in isolation while the remaining are disabled to highlight actual difference.

Model

Contains all modifications for pydantic BaseModel.

Note

In order to show any members at all, you need to enable autodoc_pydantic_model_members<autodoc_pydantic_model_members> or set :members:.

Warning

Fields containing custom objects may not be JSON serializable. This will break the schema generation by default. However, it can be handled via Show Schema JSON Error Strategy <autodoc_pydantic_model_show_json_error_strategy>.

Show Schema JSON Error Strategy

Define error handling in case a pydantic field breaks pydantic model schema generation. This occurs if a pydantic field is not JSON serializable.

Configuration (added in version 1.4.0)

conf.py

autodoc_pydantic_model_show_json_error_strategy

directive_option

model-show-json-error-strategy

Available values:

  • coerce: Keep violating fields in resulting schema but only show the title. Do not provide a warning during doc building process.
  • warn (default): Keep violating fields in resulting schema but only show the title. Provide a warning during the doc building process.
  • raise: Raises an sphinx.errors.ExtensionError during building process.

Settings

Contains all modifications for pydantic BaseSettings.

Note

In order to show any members at all, you need to enable autodoc_pydantic_settings_members<autodoc_pydantic_settings_members> or set :members:.

Warning

Fields containing custom objects may not be JSON serializable. This will break the schema generation by default. However, it can be handled via Show Schema JSON Error Strategy <autodoc_pydantic_settings_show_json_error_strategy>.

Show Schema JSON Error Strategy

Define error handling in case a pydantic field breaks pydantic settings schema generation. This occurs if a pydantic field is not JSON serializable.

Configuration (added in version 1.4.0)

conf.py

autodoc_pydantic_settings_show_json_error_strategy

directive_option

settings-show-json-error-strategy

Available values:

  • coerce: Keep violating fields in resulting schema but only show the title. Do not provide a warning during doc building process.
  • warn (default): Keep violating fields in resulting schema but only show the title. Provide a warning during the doc building process.
  • raise: Raises an sphinx.errors.ExtensionError during building process.

Fields

Validators

General

Add Fallback CSS Class

Adds fallback css classes for HTML content generated by autodoc_pydantic to prevent breaking themes which rely on the standard sphinx autodoc objtype css classes.

More concretely, the following auto-documenter directives gain the following css fallback classes:

  • pydantic_model -> class
  • pydantic_settings -> class
  • pydantic_field -> attribute
  • pydantic_validator -> method
  • pydantic_config -> class

For more, please see the corresponding FAQ<faq_add_fallback_css_class> section.

Configuration (added in version 1.6.0)

conf.py

autodoc_pydantic_add_fallback_css_class

Available values:

  • True (default): Add fallback CSS classes.
  • False: Do not add fallback CSS classes.

Note

Sphinx versions prior 4.0.0 did not include the objtype as a default css class for the corresponding docutil nodes. autodoc_pydantic will add the objtype as a css class for its generated output for older sphinx versions, too.