helpers

helpers#

import sphinx_api_relink.helpers

Helper functions for your conf.py Sphinx configuration file.

To have interlinked APIs that remain correct in older versions of your documentation (see versioning on Read the Docs), it is important to link against pinned versions of external packages. Many of these functions are useful for the configuration options of the intersphinx extension.

get_branch_name() → str[source]#

Get the branch name from the environment in a CI job.

See READTHEDOCS_VERSION and GITHUB_REF on GitHub Docs.

See also

get_git_revision() for a more robust alternative that also works locally.

get_execution_mode() → str[source]#

Get the Jupyter notebook execution mode from environment variables.

Returns "force" if the FORCE_EXECUTE_NB environment variable is set, "cache" if the EXECUTE_NB environment variable is set, and "off" otherwise. You can use this to set the nb_execution_mode option for the MyST-NB package.

from sphinx_api_relink.helpers import get_execution_mode

nb_execution_mode = get_execution_mode()

get_git_revision(*, prefer_branch: bool = False) → str[source]#

Get the current Git revision (branch, tag, or commit SHA) in your local repository.

This is a more robust alternative to get_branch_name() that also works locally or with private GitHub repositories. It can for instance be used to set the api_linkcode_rev option.

from sphinx_api_relink.helpers import get_git_revision

api_linkcode_rev = get_git_revision()

Another example is to use this function to set the repository_branch option of the Sphinx Book Theme.

from sphinx_api_relink.helpers import get_git_revision

html_theme_options = {
    "repository_branch": get_git_revision(prefer_branch=True),
    "use_edit_page_button": True,
}

Parameters:

prefer_branch –

If True, return the current branch name if no tag is found. If False, return the commit SHA if no tag is found. In the html_theme_options example above, we chose to prefer the branch name, because that makes more sense for editing pages on GitHub.

See also

ComPWA/sphinx-api-relink#22

get_package_version(package_name: str) → str[source]#

Get the version of a Python package using importlib.metadata.version().

The version is returned in the full MAJOR.MINOR.PATCH format.

from sphinx_api_relink.helpers import get_package_version

version = get_package_version("sphinx-api-relink")

pin(package_name: str) → str[source]#

Get the version number of a package based on constraints or installed version.

This is useful when setting the intersphinx_mapping in your Sphinx configuration:

from sphinx_api_relink.helpers import pin

intersphinx_mapping = {
    "attrs": (f"https://www.attrs.org/en/{pin('attrs')}", None),
}

pin_minor(package_name: str) → str[source]#

Get the version of a package with only the MAJOR.MINOR components.

Some packages use documentation URLs that only specify the MAJOR.MINOR version. An example is the NumPy API (e.g. https://numpy.org/doc/1.24).

from sphinx_api_relink.helpers import pin_minor

intersphinx_mapping = {
    "numpy": (f"https://numpy.org/doc/{pin_minor('numpy')}", None),
}

set_intersphinx_version_remapping(version_remapping: dict[str, dict[str, str]]) → None[source]#

Remap versions returned by the pin() and pin_minor() functions.

Since the pin() and pin_minor() functions return the installed version of a package, it may be necessary to remap certain versions to match the versions used in the documentation URLs of external packages, in particular when those packages have not yet released the API website for a specific release.

This function has to be called in the conf.py file before using the pin() and pin_minor() functions.

from sphinx_api_relink.helpers import set_intersphinx_version_remapping

set_intersphinx_version_remapping({
    "ipython": {
        "8.12.2": "8.12.1",
        "8.12.3": "8.12.1",
    },
    "ampform": {"0.15.12.dev.*": "0.15.11"},
})

print_once(message: str, *, color: str = '\x1b[31m') → None[source]#

Prints a message to the console only once, with optional color formatting.

Colors can be specified using ANSI escape codes from the tartley/colorama library. The default color is red.

from colorama import Fore
from sphinx_api_relink.helpers import print_once

print_once("This is an important message!", color=Fore.GREEN)

helpers

Contents

helpers#