sphinx_api_relink

import sphinx_api_relink

Helper functions for Sphinx API documentation relinking.

The following options can be set in your Sphinx configuration file to steer the behavior of the the sphinx_api_relink extension.

API documentation generation

generate_apidoc_package_path

Type:

str | list[str]

If you set this option with the path to your package(s), the extension will automatically generate API documentation using sphinx.ext.apidoc when the Sphinx build starts.

generate_apidoc_directory

Type:

str

Default:

"api"

The directory where the API documentation will be generated when using the sphinx.ext.apidoc module. This directory is relative to the Sphinx source directory. For this option to take effect, you must also set the generate_apidoc_package_path option.

generate_apidoc_excludes

Type:

list[str]

A list of paths to submodules modules that should be excluded when generating the API documentation. The paths are relative to the package path(s) specified in the generate_apidoc_package_path option.

generate_apidoc_use_compwa_template

Type:

bool

Default:

True

If set to True, the extension will use a custom template for generating the API. See this page for an example of the generated API documentation using the Sphinx Book Theme.

Intersphinx relinking

api_github_repo

Type:

str

The GitHub repository in the format "Organization/Repository" where your source code is hosted. If you set this option, the extension will link to the source code on GitHub from the documentation using the sphinx.ext.linkcode extension through its linkcode_resolve configuration option.

api_linkcode_rev

Type:

str

The Git revision (branch, tag, or commit SHA) to link to in the source code repository. This is used by the sphinx.ext.linkcode extension to generate correct links to the source code. If not set, the Git revision is determined automatically by trying the commit SHA, branch name, or latest tag and checking if its blob is available on GitHub.

Tip

get_git_revision() and get_branch_name() can be used to programmatically get the current Git revision or determine the branch name in CI jobs.

api_target_substitutions

Type:

dict[str, str | tuple[str, str]]

This option allows you to specify substitutions for type hint references in your API documentation. The keys are the original type hints, and the values are either the target reference as a string or a tuple containing the target type and reference.

api_target_types

Type:

dict[str, str]

This option allows you to specify the reference type for specific type hints in your API documentation. The keys are the type hints, and the values are the desired reference types (e.g., "obj", "class", etc.).

Submodules and Subpackages

• helpers
  • get_branch_name()
  • get_execution_mode()
  • get_git_revision()
  • get_package_version()
  • pin()
  • pin_minor()
  • set_intersphinx_version_remapping()
  • print_once()
• linkcode
  • get_linkcode_resolve()
  • LinkcodeInfo
    • LinkcodeInfo.module
    • LinkcodeInfo.fullname
  • get_blob_url()