https://github.com/patrick-kidger/hippogriffe
Tweaks for `mkdocstrings[python]`
https://github.com/patrick-kidger/hippogriffe
documentation griffe mkdocs mkdocstrings python
Last synced: 17 days ago
JSON representation
Tweaks for `mkdocstrings[python]`
- Host: GitHub
- URL: https://github.com/patrick-kidger/hippogriffe
- Owner: patrick-kidger
- License: apache-2.0
- Created: 2025-03-14T22:11:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-21T16:13:51.000Z (about 1 year ago)
- Last Synced: 2026-04-06T22:30:24.945Z (about 2 months ago)
- Topics: documentation, griffe, mkdocs, mkdocstrings, python
- Language: Python
- Homepage:
- Size: 212 KB
- Stars: 10
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Hippogriffe
This is a set of tweaks on top of the MkDocs + `mkdocstrings[python]` + `griffe` documentation stack. In particular, we:
- Add `[source]` links to GitHub to each top-level class or function.
- Pretty-format type annotations:
- Fixes unions/generics/etc. to display as e.g. `int | str` rather than just `Union`, or `tuple[int, str]` rather than just `tuple`.
- Respects your public API: if a type is declared in your documentation as `::: yourlib.Foo` then its usage in type annotations will match: `some_fn(foo: yourlib.Foo)`.
- Show base classes inline after the class.
- Drops the `-> None` return annotation from `__init__` methods.
- Attributes display as `[attr] somelib.someattr` instead of `[attr] somelib.someattr = some_value [module]`. (I don't find usually-long default values to be useful documentation, nor the 'module' tag to be informative.)
Before | After
:---------------------:|:----------------------:
 | 
## Installation
```bash
pip install hippogriffe
```
Requires MkDocs 1.6.1+ and `mkdocstrings[python]` 0.28.3+
## Usage
In `mkdocs.yml`:
```yml
...
plugins:
- hippogriffe
- mkdocstrings:
...
```
## Configuration
Hippogriffe supports the following configuration options:
```yml
plugins:
- hippogriffe:
show_bases: true/false
show_source_links: all/toplevel/none
extra_public_objects:
- foo.SomeClass
- bar.subpackage.some_function
```
**show_bases:**
If `false` then base classes will not be displayed alongside a class. Defaults to `true`.
**show_source_links:**
Sets which objects will have links to their location in the repository (as configured via the usual MkDocs `repo_url`). If `all` then all objects will have links. If `toplevel` then just `::: somelib.value` will have links, but their members will not. If `none` then no links will be added. Defaults to `toplevel`.
**extra_public_objects:**
Pretty-formatting of type annotations is done strictly: every annotation must be part of the known public API, else an error will be raised. The public API is defined as the combination of:
- Everything you document using `::: yourlib.Foo`, and all of their members.
- Anything from the standard library.
- All objects belonging to any of `extra_public_objects`.
For example,
```yml
plugins:
- hippogriffe:
extra_public_objects:
- jax.Array
- torch.Tensor
```
List each object under whatever public path `somelib.Foo` that you would like it to be displayed under (and from which it must be accessible), not whichever private path `somelib._internal.foo.Foo` it is defined at.