Helper tools for API linking

Helper tools for API linking#

This package provides helper tools and additional configuration options for the autodoc and linkcode Sphinx extensions. The autodoc_type_aliases configuration option does not always work well when using postponed evaluation of annotations (PEP 563) or when importing through typing.TYPE_CHECKING, because 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, add "sphinx_api_relink" to your extensions:

extensions = [
    "sphinx_api_relink",
]

Generate API#

To generate the API for sphinx.ext.autodoc, specify the generate_apidoc_package_path in your Sphinx configuration:

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. the ampform API). To use the default apidoc template, set:

generate_apidoc_use_compwa_template = False

Tip

See the API page for all configuration options and helper functions.

Relink type hints#

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 (see The Python Domain). 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 and api_linkcode_rev = "main" to disable determining the branch, tag, or commit SHA automatically.

Developer installation#

To contribute to the project, you need to install the package in a virtual environment. This can be done best with uv (see installation instructions here). For this, you first need to get the source code with Git:

git clone https://github.com/ComPWA/sphinx-api-relink
cd sphinx-api-relink

Now it’s simply a matter of creating and activating the virtual environment with uv sync. The dependencies for the project are ‘pinned’ in each commit through the uv.lock file.

uv sync --all-extras
source .venv/bin/activate

Formatting and linting checks are automatically performed when committing changes. This is done with pre-commit. To install the hooks in your local repository, run install pre-commit with uv:

uv tool install pre-commit --with pre-commit-uv --force-reinstall --python=3.13

and pre-commit install once:

pre-commit install --install-hooks

Poe the Poet is used as a task runner. Install it globally (within your home folder) with uv:

uv tool install poethepoet --force-reinstall --python=3.13

You can see which local CI checks it defines by running

poe

For instance, all style checks can be run with

poe style