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: 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 (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-04T00:55:21.000Z (3 months ago)
- Last Synced: 2025-02-07T07:35:47.950Z (2 months ago)
- Topics: dataclasses, griffe-extension, mkdocs, mkdocstrings, pydantic
- Language: Python
- Homepage:
- Size: 37.1 KB
- Stars: 16
- Watchers: 1
- Forks: 2
- Open Issues: 4
-
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` |
For example:
```yml
options:
extensions:
- griffe_fieldz: {include_inherited: true}
```
## Example
As an example playground for using this plugin to document pydantic, attrs, and other
dataclass-like objects, see: