Zyell/griffe-fieldz
Griffe extension to inject field metadata into mkdocstrings (supports dataclasses, pydantic, attrs, and more)
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-fieldzTo use the extension in a MkDocs project, use this configuration:
# mkdocs.yml
plugins:
- mkdocstrings:
handlers:
python:
options:
extensions:
- griffe_fieldzYou 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 |
For example:
options:
extensions:
- griffe_fieldz:
include_inherited: false
include_private: false
add_fields_to: docstring-attributes
remove_fields_from_members: falseExample
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