Changelog
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.
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
and4.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 toTabDocDirective
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
andsphinx.ext.viewcode
extensions.
Internal
Completely remove the
ModelWrapper
with theModelInspector
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
andsphinx-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.
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 specificset_members_all
.Create separate copy for every auto-documenters
option
object to prevent shared options.
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
withcoverage
.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 tocomposites
to improve naming convention.
Added
show_versions
function to show important dependency information which are relevant for tracking down bugs as part of the newutility
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
andsettings-show-field-summary
which partially addresses #14.
Internal
Add
get_fields
toinspection
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 extensionsetup
.Add version and extension meta data to
setup
.Refactor rather complex
setup
into separate functions.
Testing
Rename test directory
test-ext-autodoc-pydantic
totest-base
to streamline naming convention.Add test directory
test-edgecase-any-reference
to mock issue with failing:any:
reference to pydantic objects includingtest_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
andoption_is_false
forPydanticAutoDirective
respecting missing values via customNONE
object.Move member option processing from
__init__
todocument_members
forPydanticModelDocumenter
.Introduce
PydanticDirectiveBase
base class for all pydantic directives to remove code redundancies.
Bugfix
Documentation
Add
autosummary
explanation to usage section.
Testing
Add test module for ensuring
autosummary
interoperability.
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
andsettings-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 sectionTabDocDirective
to generate rendered examples in configuration sectionAutoCodeBlock
to generate code block from object pathAdd 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
andpydantic >= 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 withModelWrapper
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.