griffe-fieldz

Griffe extension adding support for dataclass-like things (pydantic, attrs, etc...). This extension will inject the fields of the data-class into the documentation, preventing you from duplicating field metadata in your docstrings.

It supports anything that fieldz supports, which is currently:

Installation

With pip:

pip install griffe-fieldz

To use the extension in a MkDocs project, use this configuration:

# mkdocs.yml
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extensions:
          - griffe_fieldz

You may use any of the following options, provided as a dictionary under the griffe_fieldz key.

Option	Description	Default
`include_inherited`	Include inherited fields in class parameters.	`False`
`include_private`	Include private fields in the documentation.	`False`
`add_fields_to`	Where in the documentation to add the detected fields. Must be one of: - `docstring-parameters`: add fields to the Parameters section of the docstring - `docstring-attributes`: add fields to the Attributes section of the docstring - `class-attributes`: add fields as class attributes	`docstring-parameters`
`remove_fields_from_members`	If `True`, fields are removed as class members. This is not encouraged (since fields are indeed class attributes), but will prevent duplication of the name in the docstring as well as the class. This value is ignored if `add_fields_to` is `class-attributes`.	`False`
`strip_annotated`	If `True`, strip the `Annotated` wrapper from type hints, showing only the inner type. For example, `Annotated[int, Gt(0)]` will be displayed simply as `int`.	`False`

For example:

        options:
          extensions:
          - griffe_fieldz:
              include_inherited: false
              include_private: false
              add_fields_to: docstring-attributes
              remove_fields_from_members: false
              strip_annotated: false

Example

As an example playground for using this plugin to document pydantic, attrs, and other dataclass-like objects, see: https://github.com/tlambert03/fieldz-docs-example