Relink type hints in your Sphinx API
Project description
PDG role for Sphinx
This package is a plugin for the sphinx.ext.autodoc
extension. The autodoc_type_aliases
configuration does not always work well when using postponed evaluation of annotations (PEP 563, i.e. from __future__ import annotations
) or when importing through typing.TYPE_CHECKING
, because sphinx.ext.autodoc
generates the API dynamically (not statically, as opposed to sphinx-autoapi
).
Installation
Just install through PyPI with pip
:
pip install sphinx-api-relink
Next, in your Sphinx configuration file (conf.py
), add "sphinx_api_relink"
to your extensions
:
extensions = [
"sphinx_api_relink",
]
Usage
There are two ways to relink type hint references in your API. The first one, api_target_substitutions
, should be used when the target is different than the type hint itself:
api_target_substitutions: dict[str, str | tuple[str, str]] = {
"sp.Expr": "sympy.core.expr.Expr",
"Protocol": ("obj", "typing.Protocol"),
}
The second, api_target_types
, is useful when you want to redirect the reference type. This is for instance useful when Sphinx thinks the reference is a class
, but it should be an obj
:
api_target_types: dict[str, str] = {
"RangeDefinition": "obj",
}
Generate API
To generate the API for sphinx.ext.autodoc
, add this to your conf.py
:
api_package_path = "../src/my_package" # relative to conf.py
The API is generated with the same style used by the ComPWA repositories (see e.g. ampform.rtfd.io/en/stable/api/ampform.html). To use the default template, set:
generate_apidoc_use_compwa_template = False
Other configuration values (with their defaults):
generate_apidoc_directory = "api"
generate_apidoc_excludes = ["version.py"]
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_api_relink-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7f5e3f50bc6035fc15c320559fbcf337710671952a94ad6f32c84360c2bf55dc |
|
MD5 | f57e1fc66aa5639419ed07bdb6bc6965 |
|
BLAKE2b-256 | 51c1e5cc37b8b4d8751aff758e3e6eb02d456ae9436e30737b65cbc214a9967b |