Changelog

v1.9.1 - 2024-04-12

This is a maintanance release supporting newest sphinx releases and fixing broken CI pipeline. This release officially drops support for python 3.7 at least in the CI pipeline.

Internal

  • Resolve deprecation warning from sphinx regarding tuple interface

Bugfix

  • Fix breaking Path changes in Sphinx 7.2 with in conftest.py

Testing

  • Pin transitive dependencies to avoid breaking changes in Sphinx < 5

Contributors

v1.9.0 - 2023-06-08

This is a feature release adding support for entity relationship diagrams while dropping python 3.6. Additionally, pydantic v2 is currently excluded until support will be added. Moreover, newest sphinx versions are added to test matrix.

Feature

  • Introduce erdantic-figure and erdantic-figure-collapsed configuration option for pydantic models to add entity relationship diagrams to models’ documentation either in collapsed form or as an image included to the HTML. #148.

Bugfix

  • Run github actions on newest ubuntu-22.04.

  • Fix pytest errors with sphinx>=6.1 where the type returned by autodoc_typehints_format changed.

  • Provide upper version boundary for pydantic to exclude v2 which is not supported, yet.

Internal

  • Add to_collapsable to directives.templates that provides a standardized interface to create a collapsable field.

  • Add erdantic to extras dependencies.

Documentation

  • Add descriptions for erdantic-figure and erdantic-figure-collapsed options in the configuration section.

  • Add an example of ERD in the example section.

Testing

  • Exclude python 3.6 in test matrix.

  • Include sphinx 6.0, 6.1, 6.2 and 7.0 in test matrix.

  • Add tests for erdantic-figure and erdantic-figure-collapsed.

  • Fix github actions CI pipeline due to unsupported ubuntu while upgrading to newest ubuntu-22.04.

Contributors

  • Many thanks to yves-renier for adding entity relationship diagrams and fixing the CI pipeline #148.

v1.8.0 - 2022-10-13

This is a feature and bugfix release with major internal refactorings and added support for pydantic 1.10 and sphinx 5.1 and 5.2.

Feature

  • Introduce hide-reused-validator configuration option for pydantic models and settings to hide class methods that are created while declaring functions as reusable validators #122.

Bugfix

  • Fix incorrect reference of reused validators #122.

  • Provide deterministic sort order for model’s validator summary and field’s validator list.

  • Hide pydantic user warnings in sphinx output when testing for pydantic field serializability.

Internal

  • Add ValidatorAdapter that provides a standardized interface to pydantic’s validator objects with additional metadata (e.g. root validator) for internal usage in autodoc_pydantic.

  • Introduce field_validator_mappings to inspection.ModelInspector which holds all mappings between fields and validators. It makes many helper functions of ValidatorInspector and FieldInspector obsolete. Overall, this greatly simplifies the inspection codebase.

  • Add PydanticAutoDoc.resolve_inherited_validator_reference to allow proper reference resolution for inherited validators.

Documentation

  • Add description for autodoc_pydantic_model_hide_reused_validator and autodoc_pydantic_settings_hide_reused_validator.

  • Add example section for reused validators with detailed explanation.

  • Refactor sphinx extension helper for building autodoc_pydantic docs for better readability and maintainability.

  • Add example_path to sphinx extension helper config_description.

  • Add FAQ question regarding interoperability with autoapi.

Testing

  • Include pydantic 1.10 and sphinx 5.1 / 5.2 in test matrix.

  • Provide compatibility for new pydantic and sphinx versions.

  • Fix incorrect pydantic version comparison.

Contributors

  • Thanks to GlenNicholls for reporting a bug regarding incorrect references of reused validators #122 .

  • Thanks to csm10495 for asking a question regarding autoapi interoperability #138 .

v1.7.2 - 2022-06-12

This is a bugfix release.

Bugfix

  • Adjust PydanticFieldDocumenter.can_document_member to ignore non pydantic fields #123, #128.

  • Allow pydantic models to be documented as class attributes while adjusting ModelInspector.from_child_signode to support nested object paths #124, #129.

Contributors

Internal

  • Renamed from_signode to from_child_signode for better clarity.

  • Added explicit check to raise an exception if loaded object in ModelInspector.from_child_signode is not a pydantic model.

v1.7.1 - 2022-05-30

This is a bugfix release supporting sphinx 5.0.

Bugfix

  • Adjust modified function signature of sphinx.ext.autodoc.ClassDocumenter.add_content in sphinx 5.0 which causes a type error otherwise #125 .

Packaging

  • Convert sphinx-tabs and sphinxcontrib-mermaid to optional deps and relax their version specification.

Testing

  • Add sphinx 5.0 to test matrix.

  • Adjust several tests for changed default behaviour of autodoc_typehints_format.

Contributors

  • Thanks to lukehsiao for reporting breaking changes in sphinx 5.0 #125 .

v1.7.0 - 2022-05-18

This is a feature release.

Changing behavior

  • Default values of pydantic fields such as UndefinedPydantic and Ellipsis will now be shown as None.

Bugfix

  • Fix missing validator-field references in model-show-validator-summary in case a single validator method process multiple fields.

Feature

  • Add autodoc_pydantic_field_show_optional configuration which provides [Optional] marker for pydantic fields with default_factory. This configuration is activated by default. If deactivated, default values might be displayed incorrectly. For more, see #114

  • Add autodoc_pydantic_field_swap_name_and_alias configuration which allows to use a field’s alias as a name instead of the original field name #99 .

  • Respect interaction between autodoc_pydantic_field_swap_name_and_alias with model-show-validator-summary, model-show-field-summary, validator-replace-signature and validator-list-fields by replacing the field name with field alias in rendered documentation.

Internals

  • Determining default values of pydantic fields no longer use Field.field_info.default but Field.default. As a consequence, default values such as UndefinedPydantic and Ellipsis will now be shown as None.

  • Autodocumenter PydanticFieldDocumenter now passes field-show-alias and alias to PydanticField directive. Before, only alias was passed with value to denote field-show-alias. However, since field-swap-name-and-alias was added, the value of the alias might be required even without field-show-alias being activated.

  • Refactor and split PydanticModelDocumenter.add_validators_summary in multiple methods for better readability and maintainability.

  • Add get_field_name_or_alias to PydanticAutoDoc to centrally manage the determination of field name/alias for all auto-documenters.

  • Rename sanitize_configuration_option_name into determine_app_cfg_name in directives/options/composites.py for better clarity.

  • Add configuration_names to AutoDocOptions to distinguish foreign directive options in determine_app_cfg_name which is required because field-swap-name-and-alias is also used by model/validator auto-documenters.

Documentation

  • Add example section for field-swap-name-and-alias.

  • Add configuration description for field-swap-name-and-alias.

Contributors

  • Thanks to spacemanspiff2007 for providing and supporting a feature request to show [Optional] marker #114 and a feature request to swap name and alias #99 .

v1.6.2 - 2022-04-15

This is a documentation and bugfix release supporting sphinx 4.5.

Bugfix

  • Fix incorrect source-to-doc hyperlink in users example section #96.

  • Fix incorrect [Required] mark for optional fields like Optional[int] #97.

  • Fix incorrect warning of JSON non-serializable field in case of composite types like Union. #98.

  • Fix incorrect showing of additional keyword arguments passed to pydantic Field in the field’s constraint documentation section #110.

Documentation

  • Separate example page into configuration and specifics.

  • Add examples for required and optional values.

  • Add examples for generic models.

  • Use separate python modules for user’s usage and example sections to prevent ambiguous source-to-doc hyperlinks.

Testing

  • Add sphinx 4.5 to CI.

  • Add test to ensure that optional fields do not have the [Required] mark.

  • Add test to ensure that pydantic field with composite type like Union is correctly identified as JSON serializable.

  • Add test to ensure that additional keyword arguments passed to pydantic Field are not shown in the field’s constraint documentation section.

  • Pin jinja2<3.1.0 for sphinx<4 to fix broken CI.

Contributors

  • Thanks to jgunstone for reporting a bug regarding incorrect source-to-doc hyperlink in users example section.

  • Thanks to Czaki for reporting a bug regarding incorrect warning of JSON non-serializable field in case of composite types like Union.

  • Thanks to StigKorsnes for reporting a bug regarding incorrect [Required] mark for optional fields like Optional[int]

  • Thanks to spacemanspiff2007 for reporting a bug regarding incorrect showing of additional keyword arguments passed to pydantic Field in the field’s constraint documentation section.

v1.6.1 - 2022-01-28

This is a minor bugfix release including support for sphinx 4.4.

Bugfix

  • Fix incorrect rendering of pydantic field’s description attribute which was not in line with default reST rendering of docstrings of classes or functions. #91.

Testing

  • Add test to ensure that pydantic field’s description attribute is correctly rendered.

  • Add sphinx 4.4 to CI.

  • Simplify test_autodoc_pydantic_settings_hide_paramlist_false replacing version specifics with generic assert function.

Contributors

  • Thanks to iliakur for reporting the incorrect reST rendering of pydantic field’s description attribute.

v1.6.0 - 2022-01-03

This is a feature and bug fix release including support for pydantic 1.9.

Changing behavior

  • Documented pydantic models/settings as class attributes will no longer show additional content #78.

  • Generated docutils will now have additional fallback css classes #77.

Bugfix

  • Fix a bug which occurred while documenting a pydantic model as an attribute and using bysource for model summary list order #78.

Feature

  • Remove any additional content generated by autodoc_pydantic for pydantic models/settings when documented as an attribute #78.

  • By default add fallback css classes for all docutils generated by autodoc_pydantic. This can be deactivated via newly added config autodoc_pydantic_add_fallback_css_class #77.

Testing

  • Add tests to ensure that no additional content is provided if model/settings are documented as an attribute, see test_edgecases.

  • Add tests to ensure that fallback css classes are added if required, see test_events.

  • Streamline naming convention for tests regarding edge cases.

  • Adjust tests to comply with pydantic 1.9.

  • Add pydantic 1.9 to CI.

  • Add prod_app fixture to run production sphinx app based on cmd line entry point while returning captured sphinx app and doctrees.

  • Provide important doc strings to existing autodocument, parst_rst and test_app fixtures for better understandability.

Documentation

  • Add FAQ section describing changed behaviour of models/settings when used as class attributes.

  • Add FAQ section describing fallback css classes.

  • Rename BaseModel to Model and BaseSettings to Settings in configuration section.

  • Add autodoc_pydantic_add_fallback_css_class setting to users configuration page.

  • Add ShowVersions directive to show relevant package versions of current documentation build environment in setup page of developer documentation.

Contributors

  • Thanks to StigKorsnes for reporting an unexpected behavior when using autodoc_pydantic with themes like Jupyter-Book that rely on setting css styles for default sphinx autdoc objtypes class, attribute and method #77.

  • Thanks to nchaly for reporting a bug and raising the topic of how to document models/settings as an attribute #78.

v1.5.1 - 2021-11-12

This is a minor bug fix release with testing and documentation improvements. Additionally, it adds support for sphinx 4.3.

Bugfix

  • Fix a corner-case where a module that imported numpy.typing.NDArray caused autodoc_pydantic to experience an uncaught exception #57.

Internal

  • Account for modified method signature in get_signature_prefix in sphinx 4.3 #62.

Testing

  • Fix broken CI for sphinx 3.4 due to unpinned versions of docutils. This generates new sphinx loggings which have not been present before that in turn cause tests to fail which are dependent on inspecting sphinx loggings #68.

  • Add sphinx 4.3 to CI matrix.

  • Add compatibility module to abstract away minor implementation differences between sphinx versions 4.3 and prior.

  • Add tests for development versions while continuing on error.

  • Replace codacy with codecov for code coverage reports.

  • Add code coverage for all stable and latest version.

  • Allow CI to be executed on pull requests from forks of new contributors.

Documentation

  • Add Exclude __init__ docstring section to FAQ of the user guide #58.

  • Add github issue links to topics of FAQ of the user guide.

Contributors

  • Thanks to j-carson for reporting a bug and providing a PR related to autodoc_pydantic’s inspection module #57.

  • Thanks to Yoshanuikabundi and jakobandersen for reporting and mitigating a compatibility issue with sphinx 4.3 #62.

  • Thanks to lilyminium for adding the Exclude __init__ docstring section to FAQ of the user guide #58.

v1.5.0 - 2021-10-10

This release includes major internal refactorings, new documentation sections, a new feature, a bug fix and tests for new sphinx and python versions.

Added

  • Provide summary-list-order configuration property which allows to sort summary list items in alphabetical order or by source.

Bugfix

  • Using @root_validator(pre=True) caused the sphinx build process to fail due to an incorrect implementation. This has been fixed. #55.

Testing

  • Refactor all configuration test modules removing repeated function arguments to increase readability and maintainability.

  • Add specific test to ensure that using @root_validator(pre=True) does not break the sphinx build process.

  • Add sphinx versions 4.1.0 and 4.2.0 to CI matrix.

  • Add python version 3.10 to CI matrix.

Documentation

  • Add section in configuration page describing summary-list-order.

  • Add developer design section providing gentle introduction to code base.

  • Add developer guides focusing on concrete implementation details.

  • Add class diagrams via mermaid.js.

  • Streamline naming convention for TabDocDirective for better clarity.

  • Add version parameter to TabDocDirective to show the version in which a configuration property was added.

  • Add API documentation for selected modules including directory tree with references.

  • Activate sphinxcontrib.mermaid and sphinx.ext.viewcode extensions.

Internal

  • Completely remove the ModelWrapper with the ModelInspector with all its composite classes.

  • Moving inspection logic from auto-documenters to ModelInspector.

  • Streamline naming conventions for composite classes.

  • Create separate sub directory for directive options including individual modules for composites, definitions, enums and validators.

  • Move reST templates to separate module.

Packaging

  • Update to newest versions of sphinx-rtd-theme and sphinx-tabs.

  • Add sphinxcontrib-mermaid under dev and doc dependencies.

Contributors

  • Thanks to goroderickgo for reporting a bug related to pre root validators breaking the sphinx build process #55.

v1.4.0 - 2021-08-20

This is a feature and bug release.

Added

  • Provide field-show-required configuration property. If activated, it adds a [Required] marker for pydantic fields which do not have a default value. Otherwise, misleading default values like Ellipsis or PydanticUndefined are shown. #34.

  • Include show-json-error-strategy for pydantic models and settings to define error handling in case a pydantic field breaks the JSON schema generation #8.

Bugfix

  • Respect inherited-members for field and validator summaries to prevent different members being displayed between header and body #32.

  • Improve handling of non serializable pydantic fields for JSON model generation. Using pd.DataFrame as a type annotation raised an exception instead of being handled appropriately #28.

  • Allow typed fields within doc strings to successfully reference pydantic models and settings #27.

  • Remove env key from field constraints.

Testing

  • Add explicit tests for references originating from typed fields.

  • Add more diverse tests for handling non serializable fields breaking JSON model generation.

  • Add tests for different error handling strategies regarding show-json-error-strategy.

  • Add tests for field-show-required.

  • Add tests for field and validator summaries respecting inherited-members.

Documentation

  • Add section in configuration page describing show-json-error-strategy.

  • Add section in configuration page describing field-show-required.

  • Add FAQ page with section about using inherited-members.

  • Generally overhaul the documentation to improve readability and conciseness.

Contributors

  • Thanks to davidchall for suggesting to add a [Required] marker for mandatory pydantic fields #34.

  • Thanks to matutter for reporting a bug related to incorrect field and validator summaries not respecting inherited-members #32.

  • Thanks to thomas-pedot for reporting a bug related to error handling of pydantic fields breaking JSON schema generation #28.

  • Thanks to tahoward for reporting a bug related to missing references in typed fields #27.

v1.3.1 - 2021-07-21

This is a minor release including the following:

  • Providing support for root_validator #20 .

  • Fixing a bug concerning overwriting member-order #21 .

  • Integrating flake8 for static code analysis.

Bugfix

  • Fix member-order being overwritten by autodoc pydantic’s autodocumenters #21.

Documentation

  • Add example showing representation of asterisk and root validators.

  • Add sphinx-copybutton extension.

Testing

  • Add explicit tests for asterisk and root validators.

  • Add test case ensuring that member-order is not affected by other auto-documenters.

  • Fix several tests which in fact tested wrong behaviour.

Internal

  • Refactor and simplify field validator mapping generation of inspection.ModelWrapper.

  • Replace set_default_option_with_value with specific set_members_all.

  • Create separate copy for every auto-documenters option object to prevent shared options.

Contributors

  • Thanks to roguh for submitting a feature request for root_validators #20.

  • Thanks to ybnd for submitting a bug report concerning incorrect behaviour for member-order #21

v1.3.0 - 2021-05-10

This is a release focusing on testing and packaging. It includes tests for sphinx 4.0 support. Additionally, it moves all test invocation specifications to tox.ini.

Documentation

  • Add acknowledgements to index.

  • Add detailed description for running tests with pytest and tox.

  • Convert changelog page from markdown to reST.

Testing

  • Use tox for defining different test environments (specific stable, latest stable and development). Remove test environment specifications from github ci and move it to tox.ini addressing #7.

  • Add sphinx 4.0 to test environments addressing #16.

  • Define specific test environments instead of testing all matrix combinations.

  • Provide version information about autdoc_pydantic and relevant dependencies.

Packaging

  • Replace pytest-cov with coverage.

  • Remove myst-parser dependency addressing #16.

  • Add tox for executing tests in CI.

  • Remove poetry development dependencies and replace it with explicit extras for docs, test and dev.

Internal

  • Rename util module to composites to improve naming convention.

Added

  • show_versions function to show important dependency information which are relevant for tracking down bugs as part of the new utility module.

v1.2.0 - 2021-05-09

This is a feature release adding the field summary for pydantic models/settings.

Documentation

  • Refactor and simplify sphinx extension helper module for better maintainability and readability.

  • Improve many of the available descriptions in the configuration section.

  • Provide correct markers for the actual default values in the configuration section.

Added

  • Introduce model-show-field-summary and settings-show-field-summary which partially addresses #14.

Internal

  • Add get_fields to inspection module.

v1.1.3 - 2021-05-08

This is a patch release addressing missing cross reference ability and minor refactorings.

Internal

  • Add add_domain_object_types to extension setup.

  • Add version and extension meta data to setup.

  • Refactor rather complex setup into separate functions.

Testing

  • Rename test directory test-ext-autodoc-pydantic to test-base to streamline naming convention.

  • Add test directory test-edgecase-any-reference to mock issue with failing :any: reference to pydantic objects including test_any_reference test.

  • Add test_sphinx_build test module to check that the sphinx docs build without error and warning which can be seen as an end to end test because autodoc_pydantic’s documentation is built with sphinx and contains an entire collection of usage examples for autodoc_pydantic itself.

Bugfix

  • Enable cross referencing of pydantic objects which are documented with autodoc_pydantic directives and linked via :any: role #3.

Documentation

  • Add complete configuration and fields only example to documentation.

v1.1.2 - 2021-05-06

This is a bugfix release on compatibility issues with sphinx autosummary.

Internal

  • Remove custom object import and use autodoc’s provided functionality.

  • Add option_is_true and option_is_false for PydanticAutoDirective respecting missing values via custom NONE object.

  • Move member option processing from __init__ to document_members for PydanticModelDocumenter.

  • Introduce PydanticDirectiveBase base class for all pydantic directives to remove code redundancies.

Bugfix

  • Respect .. currentmodule:: directive for object imports #12.

  • Make autosummary’s FakeDirective work with pydantic autodocumenters #11.

  • Allow AutoSummary.get_items to successfully list pydantic autodocumenters which wrap objects imported to external modules #11.

Documentation

  • Add autosummary explanation to usage section.

Testing

  • Add test module for ensuring autosummary interoperability.

Contributors

  • Thanks to antvig for reporting and testing an issue related to autosummary #11.

v1.1.1 - 2021-04-26

This is a minor release with focus on refactoring and doc strings.

Internal

  • Several minor readability refactorings.

Documentation

  • Add changelog and myst_parser for parsing markdown files.

Project

  • Add animated example to showcase difference between standard sphinx autodoc and pydantic autodoc.

  • Add project logo.

  • Add changelog.

v1.1.0 - 2021-04-24

This is small feature release enabling autodoc_pydantic to handle non JSON serializable fields properly.

Internal

  • Replace inspection methods that use models JSON schema with methods that directly access relevant pydantic object attributes.

  • Intercept non JSON serializable fields and overwrite types and default values indicating serialization error.

Documentation

  • Add explicit note about how non JSON serializable fields are handled for model-show-json and settings-show-json.

v1.0.0 - 2021-04-23

This is a major release providing API stability with main focus on extensive tests and documentation.

Added

  • Add custom css for autodoc_pydantic extension.

Internal

  • Add PydanticAutoDirective as composite class to mainly manage option/configuration management for directives.

  • Add PydanticAutoDoc as composite class to mainly manage option/configuration management for autodocumenters.

  • Unify directive options and global configuration settings via composite classes.

  • Add option validators option_members, option_one_of_factory, option_default_true, option_list_like.

Documentation

  • Add extensions to automate documentation generation:

  • ConfigurationToc to generate options/conf toc mappings from usage to configuration section

  • TabDocDirective to generate rendered examples in configuration section

  • AutoCodeBlock to generate code block from object path

  • Add user guide:

  • Installation

  • Usage

  • Configuration

  • Examples

  • Add developer guide:

  • Setting up development environment

  • Running tests

  • Building docs

  • Add .readthedocs.yaml.

Testing

  • Add test python package with code examples for test execution (same structure as sphinx tests).

  • Add fixture test_app to instantiate test app with settable configuration settings.

  • Add fixture autodocument to handle restructured text generation tests (autodocumenter tests).

  • Add fixture parse_rst to handle node generation tests from restructured text (directive tests).

  • Add autodoc/directive tests for all available configuration settings

  • Include sourcery in CI pipeline.

Packaging

  • Modify package dependencies to sphinx >=3.4 and pydantic >= 1.5.

v0.1.1 - 2021-04-04

This release adds the sphinx documentation skeleton.

Documentation

  • Add initial sphinx documentation.

v0.1.0 - 2021-03-30

This is the initial of autodoc_pydantic.

Added

  • Autodocumenter PydanticModelDocumenter with configurations:

  • model_show_json

  • model_show_config_member

  • model_show_config_summary

  • model_show_validator_members

  • model_show_validator_summary

  • model_hide_paramlist

  • model_undoc_members

  • model_members

  • model_member_order

  • model_signature_prefix

  • Autodocumenter PydanticSettingsDocumenter with configurations:

  • settings_show_json

  • settings_show_config_member

  • settings_show_config_summary

  • settings_show_validator_members

  • settings_show_validator_summary

  • settings_hide_paramlist

  • settings_undoc_members

  • settings_members

  • settings_member_order

  • settings_signature_prefix

  • Autodocumenter PydanticFieldDocumenter with configurations:

  • field_list_validators

  • field_doc_policy

  • field_show_constraints

  • field_show_alias

  • field_show_default

  • field_signature_prefix

  • Autodocumenter PydanticValidatorDocumenter with configurations:

  • validator_signature_prefix

  • validator_replace_signature

  • validator_list_fields

  • Autodocumenter PydanticConfigClassDocumenter with configurations:

  • config_signature_prefix

  • config_members

  • Directives PydanticModel, PydanticSettings, PydanticField, PydanticValidator, PydanticConfigClass

Internal

  • Add inspection along with ModelWrapper module providing functionality to inspect pydantic objects to retrieve relevant informations for documentation.

Testing

  • Add end to end tests for autodocumenters and directives.

  • Setup github actions for CI.

  • Add codacy integration.

  • Add code coverage.

Packaging

  • Use poetry for package management.

  • Add pyproject.toml.

  • Add github action to upload to PyPI upon version tags on main branch.