ensembl.utils.docs package#

Centralised Sphinx configuration and helpers for Ensembl documentation.

This subpackage is intentionally not imported by ensembl.utils itself, so import ensembl.utils keeps working without the documentation toolchain installed. The Sphinx/theme dependencies live behind the docs extra:

pip install ensembl-utils[docs]
ensembl.utils.docs.build_config(*, project, repo_url, docs_base_url, release=None, json_url=None, coverage_root=None, include_entrypoints=False, add_pypi_icon=False, **overrides)[source]#

Return the Ensembl-standard Sphinx configuration as a mapping.

Parameters:

  • project (str) – Human-readable project name, e.g. "ensembl-utils".

  • repo_url (str) – GitHub or GitLab URL for this repository, used to build the source link.

  • docs_base_url (str) – Public base URL where the docs are published; the version switcher JSON is expected at {docs_base_url}/switcher.json.

  • release (Optional[str], default: None) – Release version the switcher highlights as current.

  • json_url (Optional[str], default: None) – Location of the switcher JSON. If omitted, hosted/CI builds point at {docs_base_url}/switcher.json and local builds use the relative _static/switcher.json.

  • coverage_root (Union[str, PathLike[str], None], default: None) – Absolute path to the directory where pytest’s HTML coverage report folder is generated to include it with the documentation.

  • include_entrypoints (bool, default: False) – When True, adds ensembl.utils.docs.entrypoints_table to extensions so the CLI entry-points table is auto-injected into the target Markdown file at build time.

  • add_pypi_icon (bool, default: False) – When True, adds the PyPI icon and link to the project at the top right of the page.

  • **overrides (Any) – Any extra conf.py values; these win over the defaults.

Return type:

dict[str, Any]

Returns:

A dictionary suitable for injecting into a conf.py namespace.

ensembl.utils.docs.configure(namespace, **kwargs)[source]#

Populate a conf.py namespace in place with the Ensembl defaults.

Call at the top of docs/conf.py as configure(globals(), ...). See build_config() for the accepted keyword arguments.

Parameters:

  • namespace (dict[str, Any]) – The conf.py module namespace to populate, normally passed as globals().

  • **kwargs (Any) – Forwarded verbatim to build_config().

Return type:

None

ensembl.utils.docs.setup(app)[source]#

Register the app-level configuration with Sphinx.

Registered automatically because "ensembl.utils.docs" is added to extensions by build_config(). This is where things that need the running application go (custom CSS, directives, event hooks).

The package _static directory (containing ensembl.css) is appended to html_static_path on the config-inited event, after the consumption of conf.py has finished executing. This means repos can freely set or extend html_static_path without clobbering the shared assets, and shared assets never clobber repo-local ones, since later entries lose on name collision.

Parameters:

app (Sphinx) – The Sphinx application object.

Return type:

dict[str, Any]

Returns:

Sphinx extension metadata.

Submodules#

ensembl.utils.docs.config module#

Shared Sphinx configuration for Ensembl documentation builds.

Downstream repositories drive their docs/conf.py from this module:

from ensembl.utils.docs import configure

configure(
    globals(),
    project="ensembl-utils",
    repo_url="https://github.com/Ensembl/ensembl-utils",
    docs_base_url="https://ensembl.github.io/ensembl-utils",
)

Any standard Sphinx setting can be tweaked after the configure call by reassigning or mutating the matching module-level variable, e.g. extensions += ["sphinx_click"] or html_theme_options["announcement"] = ....

ensembl.utils.docs.config.build_config(*, project, repo_url, docs_base_url, release=None, json_url=None, coverage_root=None, include_entrypoints=False, add_pypi_icon=False, **overrides)[source]#

Return the Ensembl-standard Sphinx configuration as a mapping.

Parameters:

  • project (str) – Human-readable project name, e.g. "ensembl-utils".

  • repo_url (str) – GitHub or GitLab URL for this repository, used to build the source link.

  • docs_base_url (str) – Public base URL where the docs are published; the version switcher JSON is expected at {docs_base_url}/switcher.json.

  • release (Optional[str], default: None) – Release version the switcher highlights as current.

  • json_url (Optional[str], default: None) – Location of the switcher JSON. If omitted, hosted/CI builds point at {docs_base_url}/switcher.json and local builds use the relative _static/switcher.json.

  • coverage_root (Union[str, PathLike[str], None], default: None) – Absolute path to the directory where pytest’s HTML coverage report folder is generated to include it with the documentation.

  • include_entrypoints (bool, default: False) – When True, adds ensembl.utils.docs.entrypoints_table to extensions so the CLI entry-points table is auto-injected into the target Markdown file at build time.

  • add_pypi_icon (bool, default: False) – When True, adds the PyPI icon and link to the project at the top right of the page.

  • **overrides (Any) – Any extra conf.py values; these win over the defaults.

Return type:

dict[str, Any]

Returns:

A dictionary suitable for injecting into a conf.py namespace.

ensembl.utils.docs.config.configure(namespace, **kwargs)[source]#

Populate a conf.py namespace in place with the Ensembl defaults.

Call at the top of docs/conf.py as configure(globals(), ...). See build_config() for the accepted keyword arguments.

Parameters:

  • namespace (dict[str, Any]) – The conf.py module namespace to populate, normally passed as globals().

  • **kwargs (Any) – Forwarded verbatim to build_config().

Return type:

None

ensembl.utils.docs.entrypoints_ext module#

Sphinx extension: auto-inject a CLI entry-points reference table into a Markdown page.

At builder-inited time this extension:

  1. Reads [project.scripts] from the pyproject.toml.

  2. Builds a Markdown table mapping each script name to its Python target (package.module:function).

  3. Writes the table between two sentinel comments inside the target Markdown file, replacing whatever was there from a previous build so the file stays under version control and is always up-to-date.

Enable it via build_config():

configure(
    globals(),
    ...,
    include_entrypoints=True,
)

Optionally override the defaults in conf.py after the configure() call:

entrypoints_target_file = "user_guide/usage.md"  # relative to docs source dir
entrypoints_toml_file = "../pyproject.toml"  # relative to docs source dir
ensembl.utils.docs.entrypoints_ext.setup(app)[source]#

Register the extension with Sphinx.

Adds two optional conf.py configuration values:

  • entrypoints_target_file: Path to the Markdown file to inject into, relative to the Sphinx source directory.

  • entrypoints_toml_file: Path to pyproject.toml, relative to the Sphinx source directory.

Parameters:

app (Sphinx) – The Sphinx application object.

Return type:

dict[str, Any]

Returns:

Sphinx extension metadata.

ensembl.utils.docs.switcher module#

Update the switcher JSON file with a new version entry.

Adds a new version to the PyData Sphinx Theme version switcher dropdown. Usage: update_docs_switcher –base-url <base_url> –version <version> <path_to_switcher_json>

ensembl.utils.docs.switcher.main()[source]#

Script’s main entry point.

Return type:

None