Autodoc-pydantic

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/lukehsiao) for reporting
breaking changes in sphinx 5.0
[125](https://github.com/mansenfranzen/autodoc_pydantic/issues/125)
.

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/spacemanspiff2007)
for providing and supporting a feature request to show `[Optional]`
marker
[114](https://github.com/mansenfranzen/autodoc_pydantic/issues/114)
and a feature request to swap name and alias
[99](https://github.com/mansenfranzen/autodoc_pydantic/issues/99) .

This is a documentation and bugfix release supporting sphinx 4.5.

Bugfix

- Fix incorrect source-to-doc hyperlink in users example section
[96](https://github.com/mansenfranzen/autodoc_pydantic/issues/96).
- Fix incorrect `[Required]` mark for optional fields like
`Optional[int]`
[97](https://github.com/mansenfranzen/autodoc_pydantic/issues/97).
- Fix incorrect warning of JSON non-serializable field in case of
composite types like `Union`.
[98](https://github.com/mansenfranzen/autodoc_pydantic/issues/98).
- Fix incorrect showing of additional keyword arguments passed to
pydantic [Field]{.title-ref} in the field\'s constraint
documentation section
[110](https://github.com/mansenfranzen/autodoc_pydantic/issues/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]{.title-ref} 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](https://github.com/jgunstone) for reporting a
bug regarding incorrect source-to-doc hyperlink in users example
section.
- Thanks to [Czaki](https://github.com/Czaki) for reporting a bug
regarding incorrect warning of JSON non-serializable field in case
of composite types like `Union`.
- Thanks to [StigKorsnes](https://github.com/StigKorsnes) for
reporting a bug regarding incorrect `[Required]` mark for optional
fields like `Optional[int]`
- Thanks to [spacemanspiff2007](https://github.com/spacemanspiff2007)
for reporting a bug regarding incorrect showing of additional
keyword arguments passed to pydantic [Field]{.title-ref} in the
field\'s constraint documentation section.

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/iliakur) for reporting the
incorrect reST rendering of pydantic field\'s `description`
attribute.

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](https://github.com/mansenfranzen/autodoc_pydantic/issues/78).
- Generated docutils will now have additional fallback css classes
[77](https://github.com/mansenfranzen/autodoc_pydantic/issues/77).

Bugfix

- Fix a bug which occurred while documenting a pydantic model as an
attribute and using [bysource]{.title-ref} for model summary list
order
[78](https://github.com/mansenfranzen/autodoc_pydantic/issues/78).

Feature

- Remove any additional content generated by **autodoc_pydantic** for
pydantic models/settings when documented as an attribute
[78](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/77).

Testing

- Add tests to ensure that no additional content is provided if
model/settings are documented as an attribute, see
[test_edgecases]{.title-ref}.
- Add tests to ensure that fallback css classes are added if required,
see [test_events]{.title-ref}.
- 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](https://github.com/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/77).
- Thanks to [nchaly](https://github.com/nchaly) for reporting a bug
and raising the topic of how to document models/settings as an
attribute
[78](https://github.com/mansenfranzen/autodoc_pydantic/issues/78).

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

Internal

- Account for modified method signature in `get_signature_prefix` in
sphinx 4.3
[62](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/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](https://github.com/mansenfranzen/autodoc_pydantic/issues/58).
- Add github issue links to topics of FAQ of the user guide.

Contributors

- Thanks to [j-carson](https://github.com/j-carson) for reporting a
bug and providing a PR related to autodoc_pydantic\'s inspection
module
[57](https://github.com/mansenfranzen/autodoc_pydantic/issues/57).
- Thanks to [Yoshanuikabundi](https://github.com/Yoshanuikabundi) and
[jakobandersen](https://github.com/jakobandersen) for reporting and
mitigating a compatibility issue with sphinx 4.3
[62](https://github.com/mansenfranzen/autodoc_pydantic/issues/62).
- Thanks to [lilyminium](https://github.com/lilyminium) for adding the
`Exclude __init__ docstring` section to FAQ of the user guide
[58](https://github.com/mansenfranzen/autodoc_pydantic/issues/58).