Adding field-show-examples to show the examples for a field

[roliveira]

I will follow the adding new features guide to summarise this PR.

1. Provide rationale

This PR follows the initial discussion in #186. It implements the examples field when available in a model.
It should be enough to close #186. This PR won't handle cases where there are examples present in the json_schema_extra dictionary.

2. Specify the feature

The examples field is available in Pydantic and part of several projects (e.g. FastAPI, transformers). It provides additional context on the usage of the field. This is particularly important for complex models, but still useful in other cases.

3. Derive tests

The tests are implemented in tests/test_configuration_fields.py. Three tests were added:

• tests/test_configuration_fields.py::test_autodoc_pydantic_field_show_examples_true
• tests/test_configuration_fields.py::test_autodoc_pydantic_field_show_examples_false
• tests/test_configuration_fields.py::test_autodoc_pydantic_field_show_examples_ignore_extra

You can run them collectively with the other tests using poetry run pytest or individually by using poetry run pytest tests/test_configuration_fields.py::name_of_class

The conftest.py was also updated to include the False default configuration and keep the behaviour of CONF_DEACTIVATE as expected.

4. Add configuration settings

A new boolean configuration was added called field_show_examples. The configuration behaves like all others *show* configurations accepting either True or False and it defaults to True.

5. Implement behaviour

The implemented behaviour was achieved with the support of autodoc_pydantic/inspection.py::FieldInspector.has_examples and autodoc_pydantic/inspection.py::FieldInspector.get_examples. The string to add the examples is generated by autodoc_pydantic/directives/autodocumented.py::PydanticFieldDocumenter.add_examples which is now ran in autodoc_pydantic/directives/autodocumented.py::PydanticFieldDocumenter.add_content

6. Update document

The documentation was updated to include the description in the configuration.rst and the default usage_automodule was also updated in usage.rst to showcase a simple field example with examples.

[mansenfranzen]

Hi @roliveira,

thanks for this great PR! It already contains all the relevant points since you've followed the guide from the docs. I'm happy to see someone using it ;-).

Much apologies for my late response :-(. I hope to look into your PR in more detail (running tests etc) during the next days. I will come back to you, soon.