Relink type hints in your Sphinx API
Project description
sphinx-api-relink
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",
}
The extension can also link to the source code on GitHub through the sphinx.ext.linkcode
extension. To activate, specify the GitHub organization and the repository name as follows:
api_github_repo: str = "ComPWA/sphinx-api-relink"
Set api_linkcode_debug = True
to print the generated URLs to the console.
Generate API
To generate the API for sphinx.ext.autodoc
, add this to your conf.py
:
generate_apidoc_package_path = "../src/my_package" # relative to conf.py
Multiple packages can be listed as well:
generate_apidoc_package_path = [
"../src/package1",
"../src/package2",
]
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.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0c0aa6454dcb7a23cc47142d3bc13bf7799cb2205c8df1c811d88b60a4a08924 |
|
MD5 | 8e0954e2026a052fed801328f9809be5 |
|
BLAKE2b-256 | 8e868da0bf107cc4dab51fd3831f3c96d9b1eb01b36f55d1798152aaa28551d1 |