Autodoc-pydantic

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/goroderickgo) for
reporting a bug related to pre root validators breaking the sphinx
build process
[55](https://github.com/mansenfranzen/autodoc_pydantic/issues/55).

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/8).

Bugfix

- Respect `inherited-members` for field and validator summaries to
prevent different members being displayed between header and body
[32](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/28).
- Allow typed fields within doc strings to successfully reference
pydantic models and settings
[27](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/davidchall) for suggesting
to add a `[Required]` marker for mandatory pydantic fields
[34](https://github.com/mansenfranzen/autodoc_pydantic/issues/34).
- Thanks to [matutter](https://github.com/matutter) for reporting a
bug related to incorrect field and validator summaries not
respecting `inherited-members`
[32](https://github.com/mansenfranzen/autodoc_pydantic/issues/32).
- Thanks to [thomas-pedot](https://github.com/thomas-pedot) for
reporting a bug related to error handling of pydantic fields
breaking JSON schema generation
[28](https://github.com/mansenfranzen/autodoc_pydantic/issues/28).
- Thanks to [tahoward](https://github.com/tahoward) for reporting a
bug related to missing references in typed fields
[27](https://github.com/mansenfranzen/autodoc_pydantic/issues/27).

This is a minor release including the following:

- Providing support for `root_validator`
[20](https://github.com/mansenfranzen/autodoc_pydantic/issues/20) .
- Fixing a bug concerning overwriting `member-order`
[21](https://github.com/mansenfranzen/autodoc_pydantic/issues/21) .
- Integrating flake8 for static code analysis.

Bugfix

- Fix `member-order` being overwritten by autodoc pydantic\'s
autodocumenters
[21](https://github.com/mansenfranzen/autodoc_pydantic/issues/21).

Documentation

- Add example showing representation of asterisk and root validators.
- Add [sphinx-copybutton]{.title-ref} 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](https://github.com/roguh) for submitting a feature
request for `root_validators`
[20](https://github.com/mansenfranzen/autodoc_pydantic/issues/20).
- Thanks to [ybnd](https://github.com/ybnd) for submitting a bug
report concerning incorrect behaviour for `member-order`
[21](https://github.com/mansenfranzen/autodoc_pydantic/issues/21)

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/7).
- Add sphinx 4.0 to test environments addressing
\[16](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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.

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/14).

Internal

- Add `get_fields` to `inspection` module.

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/3).

Documentation

- Add *complete configuration* and *fields only* example to
documentation.