https://github.com/patrick-kidger/hippogriffe
Better Python documentation
https://github.com/patrick-kidger/hippogriffe
documentation griffe mkdocs mkdocstrings python
Last synced: about 2 months ago
JSON representation
Better Python documentation
- Host: GitHub
- URL: https://github.com/patrick-kidger/hippogriffe
- Owner: patrick-kidger
- License: apache-2.0
- Created: 2025-03-14T22:11:21.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-03-15T21:28:24.000Z (about 2 months ago)
- Last Synced: 2025-03-15T21:50:05.301Z (about 2 months ago)
- Topics: documentation, griffe, mkdocs, mkdocstrings, python
- Language: Python
- Homepage:
- Size: 170 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- 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.
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_modules:
- foo
- bar
```
**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_modules:**
A list of module names whose elements should be treated as part of the public API. 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_modules`.
For example,
```yml
plugins:
- hippogriffe:
extra_public_modules:
- jax
- torch
```