Skip to content

ComPWA/sphinx-api-relink

Folders and files

NameName
Last commit message
Last commit date
Oct 29, 2024
Oct 18, 2024
Oct 14, 2024
Oct 29, 2024
Oct 18, 2024
Oct 18, 2024
Oct 18, 2024
Oct 29, 2024
Dec 3, 2023
Oct 18, 2024
Dec 3, 2023
Oct 29, 2024
Dec 3, 2023
Oct 18, 2024
Oct 29, 2024

Repository files navigation

sphinx-api-relink

PyPI package Supported Python versions BSD 3-Clause license Open in Visual Studio Code CI status Checked with mypy pre-commit.ci status Spelling checked code style: prettier Ruff uv

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