https://github.com/pyapp-kit/griffe-fieldz
Griffe extension to inject field metadata into mkdocstrings (supports dataclasses, pydantic, attrs, and more)
https://github.com/pyapp-kit/griffe-fieldz
dataclasses griffe-extension mkdocs mkdocstrings pydantic
Last synced: about 2 months ago
JSON representation
Griffe extension to inject field metadata into mkdocstrings (supports dataclasses, pydantic, attrs, and more)
- Host: GitHub
- URL: https://github.com/pyapp-kit/griffe-fieldz
- Owner: pyapp-kit
- License: bsd-3-clause
- Created: 2023-11-04T19:33:15.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-12T01:50:02.000Z (2 months ago)
- Last Synced: 2025-08-24T21:29:20.008Z (about 2 months ago)
- Topics: dataclasses, griffe-extension, mkdocs, mkdocstrings, pydantic
- Language: Python
- Homepage:
- Size: 53.7 KB
- Stars: 21
- Watchers: 2
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# griffe-fieldz
[](https://github.com/pyapp-kit/griffe-fieldz/raw/main/LICENSE)
[](https://pypi.org/project/griffe-fieldz)
[](https://python.org)
[](https://github.com/pyapp-kit/griffe-fieldz/actions/workflows/ci.yml)
[](https://codecov.io/gh/pyapp-kit/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](https://github.com/pyapp-kit/fieldz)
supports, which is currently:
- [`dataclasses.dataclass`](https://docs.python.org/3/library/dataclasses.html#dataclasses.dataclass)
- [`pydantic.BaseModel`](https://docs.pydantic.dev/latest/)
- [`attrs.define`](https://www.attrs.org/en/stable/overview.html)
- [`msgspec.Struct`](https://jcristharif.com/msgspec/)
## Installation
With `pip`:
```bash
pip install griffe-fieldz
```
To use the extension in a MkDocs project, use this configuration:
```yaml
# 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` |
For example:
```yml
options:
extensions:
- griffe_fieldz:
include_inherited: false
include_private: false
add_fields_to: docstring-attributes
remove_fields_from_members: false
```
## Example
As an example playground for using this plugin to document pydantic, attrs, and other
dataclass-like objects, see: