sphinx-api-relink 0.0.12

Relink type hints in your Sphinx API

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"]