griffe-fieldz

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:

• dataclasses.dataclass
• pydantic.BaseModel
• attrs.define
• msgspec.Struct

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