Skip to main content

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
old new

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)

Source distribution for hippogriffe 0.2.2
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)

Table of built distributions (wheels) for hippogriffe 0.2.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page