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 | strrather than justUnion, ortuple[int, str]rather than justtuple. - Respects your public API: if a type is declared in your documentation as
::: yourlib.Foothen its usage in type annotations will match:some_fn(foo: yourlib.Foo).
- Fixes unions/generics/etc. to display as e.g.
- Show base classes inline after the class.
- Drops the
-> Nonereturn annotation from__init__methods. - Attributes display as
[attr] somelib.someattrinstead 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
pip install hippogriffe
Requires MkDocs 1.6.1+ and mkdocstrings[python] 0.28.3+
Usage
In mkdocs.yml:
...
plugins:
- hippogriffe
- mkdocstrings:
...
Configuration
Hippogriffe supports the following configuration options:
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,
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.
Metadata
Release files for hippogriffe 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hippogriffe-0.2.2.tar.gz | 14.0 kB | Without provenance | Details for hippogriffe-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hippogriffe-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for hippogriffe-0.2.2-py3-none-any.whl |
Total release size: 33.4 kB
Release files / hippogriffe-0.2.2.tar.gz
| Download URL | hippogriffe-0.2.2.tar.gz |
|---|---|
| Size | 14.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9bb59c1277959bedc94baadc8a2933121c4e838dc3237b81f95864f2b509068d
|
|
BLAKE2b-256 checksum How to use checksums |
fde912cf378552b8ec916901bd3e04910bc4fceb1a8f94cfddc61ad1f9afc51e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Release files / hippogriffe-0.2.2-py3-none-any.whl
| Download URL | hippogriffe-0.2.2-py3-none-any.whl |
|---|---|
| Size | 19.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61f38bad68eeefcf175fb5436070519b1dcda7bef52e49c0d69f0723b4de07d9
|
|
BLAKE2b-256 checksum How to use checksums |
f7d6c087b990a3299d5d4c46a26f7b927bff000f7ec11a0dd607b8334b0ee2d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.12
|
Security for hippogriffe 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.