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 ¶ function[source] function[source] gp_sphinx.config.merge_sphinx_config ¶

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-gp-theme (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, ogp_site_name (for sphinx_gp_opengraph), site_url and sitemap_url_scheme (for sphinx_gp_sitemap) are auto-computed. The sitemap scheme defaults to "{link}" because git-pull.com sites deploy flat at the project root, with no {lang}{version} path segments; multilingual or version-pinned deployments can override it via overrides. All auto-computed values can be overridden via overrides.

Parameters (17)

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_autodoc_argparse.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.
vite_orchestration (bool) – When True (default False), prepends "sphinx_vite_builder" to the active extension list and sets sphinx_vite_builder_root from gp_furo_theme.get_vite_root() so contributors running sphinx-autobuild get the Vite watch fired automatically. The orchestration is a no-op for sphinx-build (mode resolves to "prod"), so wheels published to PyPI carry no Node runtime requirement.
**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-gp-theme'

>>> len(conf["extensions"]) >= 12
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/'

>>> conf["sitemap_url_scheme"]
'{link}'

The sitemap scheme can still be overridden when needed:

>>> conf = merge_sphinx_config(
...     project="test",
...     version="1.0",
...     copyright="2026",
...     docs_url="https://test.org",
...     sitemap_url_scheme="{lang}/{version}/{link}",
... )
>>> conf["sitemap_url_scheme"]
'{lang}/{version}/{link}'

When docs_url is provided, merge_sphinx_config() also auto-derives the ogp_* and sitemap_* keys consumed by the SEO extensions (sphinx_gp_opengraph, sphinx_gp_sitemap). See From docs_url for the full mapping.

make_linkcode_resolve¶

gp_sphinx.config.make_linkcode_resolve(package_module, github_url, src_dir='src', source_branch='main') ¶ function[source] function[source] gp_sphinx.config.make_linkcode_resolve(package_module, github_url, src_dir='src', source_branch='main') ¶

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.

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").
source_branch (str) – The fallback branch for development versions (default "main").

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[source] function[source] gp_sphinx.config.deep_merge(base, override) ¶

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.

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[source] function[source] gp_sphinx.config.setup(app) ¶

Configure Sphinx app hooks for gp-sphinx workarounds.

Registers the bundled spa-nav.js script, wires the copy-button configuration bridge, the FOWT-prevention head snippet, and connects the remove_tabs_js post-build hook.

Parameters:: app (Sphinx) – The Sphinx application object.
Return type:: None

API Reference¶

merge_sphinx_config¶

make_linkcode_resolve¶

Wiring into conf.py¶

deep_merge¶

setup¶

Wiring into conf.py ¶