compwa/sphinx-api-relink

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

sphinx-api-relink's Issues

"Suggest edit" button broken

The "Suggest edit" button is broken if the ref used to point to the source code is a commit. This is because you cannot edit files on GitHub if you are not on a branch.

Provide rev-only version of `get_blob_url()` in `helpers` module

The get_blob_url() uses an exact SHA or ref from the local repository and is actually quite useful for setting values like repository_branch. Currently, most repositories use get_branch_name(), which only gets rev info from the environment variables on GitHub Actions or Read the docs.

Add option to skip URL-check in `linkcode_resolve`

If api_github_repo is set in conf.py, sphinx-api-relink will check if the current SHA or default branch exists on the GitHub repository. For this, it needs access to the repository and this is not the case if the repo is private. We therefore need an option like:

api_skip_fallback: bool = False