API Reference

Public API for building Sphinx configurations and source link resolvers.

For shared defaults and configuration options, see Configuration.

merge_sphinx_config

gp_sphinx.config.merge_sphinx_config(*, project, version, copyright, extensions=None, extra_extensions=None, remove_extensions=None, theme_options=None, source_repository=None, source_branch='main', light_logo=None, dark_logo=None, docs_url=None, intersphinx_mapping=None, **overrides)function

Build a complete Sphinx conf namespace from shared defaults.

Returns a flat dictionary suitable for injection into a docs/conf.py module namespace via globals().update(conf).

The default theme is sphinx-gptheme (a Furo child theme bundled in this package). Sidebars, templates, CSS, and JS are provided by the theme automatically.

When source_repository is provided, issue_url_tpl is auto-computed for the linkify_issues extension. When docs_url is provided, ogp_site_url, ogp_image, and ogp_site_name are auto-computed for sphinxext.opengraph. All auto-computed values can be overridden via overrides.

Return type:

dict[str, Any]

Parameters:

  • project (str) – Sphinx project name.

  • version (str) – Project version string.

  • copyright (str) – Copyright string.

  • extensions (list[str] | None) – Replace the default extension list entirely. Usually not needed.

  • extra_extensions (list[str] | None) – Add extensions to the defaults (e.g., ["sphinx_argparse_neo.exemplar"]).

  • remove_extensions (list[str] | None) – Remove specific defaults (e.g., ["sphinx_design"]).

  • theme_options (dict | None) – Deep-merged with default theme options.

  • source_repository (str | None) – GitHub repository URL.

  • source_branch (str) – Default branch name.

  • light_logo (str | None) – Path to light-mode logo.

  • dark_logo (str | None) – Path to dark-mode logo.

  • docs_url (str | None) – Documentation site URL (e.g., "https://libtmux.git-pull.com"). Used to auto-compute ogp_site_url and ogp_site_name.

  • intersphinx_mapping (dict | None) – Intersphinx targets.

  • **overrides (Any) – Any additional Sphinx config values.

Returns:

Complete Sphinx configuration namespace including a setup function for workaround hooks.

Return type:

dict[str, Any]

Examples

>>> conf = merge_sphinx_config(
...     project="test",
...     version="1.0",
...     copyright="2026",
... )
>>> conf["project"]
'test'

>>> conf["version"]
'1.0'

>>> conf["html_theme"]
'sphinx-gptheme'

>>> len(conf["extensions"]) >= 13
True

>>> callable(conf["setup"])
True

Extra extensions are appended:

>>> conf = merge_sphinx_config(
...     project="test",
...     version="1.0",
...     copyright="2026",
...     extra_extensions=["my_ext"],
... )
>>> "my_ext" in conf["extensions"]
True

Extensions can be removed:

>>> conf = merge_sphinx_config(
...     project="test",
...     version="1.0",
...     copyright="2026",
...     remove_extensions=["sphinx_design"],
... )
>>> "sphinx_design" in conf["extensions"]
False

Auto-computed values from source_repository and docs_url:

>>> conf = merge_sphinx_config(
...     project="test",
...     version="1.0",
...     copyright="2026",
...     source_repository="https://github.com/org/test/",
...     docs_url="https://test.org",
... )
>>> conf["issue_url_tpl"]
'https://github.com/org/test/issues/{issue_id}'

>>> conf["ogp_site_url"]
'https://test.org'

make_linkcode_resolve

gp_sphinx.config.make_linkcode_resolve(package_module, github_url, src_dir='src')function

Create a linkcode_resolve function for sphinx.ext.linkcode.

Generates a resolver that maps Python objects to their source location on GitHub. The returned function follows the interface expected by sphinx.ext.linkcode.

Return type:

Callable[[str, dict[str, str]], str | None]

Parameters:

  • package_module (types.ModuleType) – The top-level package module (e.g., import libtmux; libtmux). Used to compute relative file paths.

  • github_url (str) – Base GitHub repository URL (e.g., "https://github.com/tmux-python/libtmux").

  • src_dir (str) – Directory containing the source package (default "src").

Returns:

A function suitable for linkcode_resolve in Sphinx config.

Return type:

Callable[[str, dict[str, str]], str | None]

Examples

>>> import gp_sphinx

>>> resolver = make_linkcode_resolve(
...     gp_sphinx,
...     "https://github.com/git-pull/gp-sphinx",
... )
>>> callable(resolver)
True

Wiring into conf.py

Pass the resolver to merge_sphinx_config() via **overrides. sphinx.ext.linkcode is auto-appended to extensions when linkcode_resolve is provided:

import my_project
from gp_sphinx.config import make_linkcode_resolve, merge_sphinx_config

conf = merge_sphinx_config(
    project="my-project",
    version=my_project.__version__,
    copyright="2026, My Name",
    source_repository="https://github.com/my-org/my-project/",
    linkcode_resolve=make_linkcode_resolve(
        my_project,
        "https://github.com/my-org/my-project",
    ),
)
globals().update(conf)

deep_merge

gp_sphinx.config.deep_merge(base, override)function

Recursively merge override into base, returning a new dict.

When both values for a key are dicts, they are merged recursively. Otherwise the value from override wins.

Return type:

dict[str, Any]

Parameters:

  • base (dict) – The base dictionary.

  • override (dict) – The dictionary whose values take precedence.

Returns:

A new merged dictionary.

Return type:

dict

Examples

>>> deep_merge({"a": 1, "b": {"x": 10}}, {"b": {"y": 20}})
{'a': 1, 'b': {'x': 10, 'y': 20}}

>>> deep_merge({"a": 1}, {"a": 2, "c": 3})
{'a': 2, 'c': 3}

setup

gp_sphinx.config.setup(app)function

Configure Sphinx app hooks for gp-sphinx workarounds.

Registers the bundled spa-nav.js script and connects the remove_tabs_js post-build hook.

Return type:

None

Parameters:

app (Sphinx) – The Sphinx application object.