Relink type hints in your Sphinx API
Reason this release was yanked:
Sphinx linkcheck builder not supported
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 also links to the source code on GitHub through the sphinx.ext.linkcode
extension. You need to 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
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.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4a7a5b312a07715a8af166e28fc050a639af8c0863782ad4b1cd4d0435855646 |
|
MD5 | 8e1d6bb3b5b794879c4da14865622b65 |
|
BLAKE2b-256 | 2e46bc2bb08b0835b8d0b3aa2f53f4e00092ab36b198a0019b8f2d102f39f0df |