How to

Downstream conf.py

from __future__ import annotations

from gp_sphinx.config import merge_sphinx_config

import my_project

conf = merge_sphinx_config(
    project="my-project",
    version=my_project.__version__,
    copyright="2026, Your Name",
    source_repository="https://github.com/your-org/my-project/",
    docs_url="https://my-project.example.com/",
    intersphinx_mapping={
        "py": ("https://docs.python.org/3", None),
    },
)
globals().update(conf)

What it injects

  • Shared extension defaults, theme defaults, fonts, MyST, napoleon, copybutton, and rediraffe settings.

  • Auto-computed issue_url_tpl and theme source-repository wiring from source_repository.

  • Auto-computed SEO values when docs_url is set: ogp_site_url, ogp_site_name, ogp_image for sphinx-gp-opengraph, plus site_url and sitemap_url_scheme for sphinx-gp-sitemap. See From docs_url for the canonical mapping.

  • A setup(app) hook that registers js/spa-nav.js and removes tabs.js after HTML builds.

  • Support for appending sphinx.ext.linkcode automatically when linkcode_resolve is supplied in **overrides.

See Configuration for the complete parameter reference and every shared DEFAULT_* constant.

SEO emission for free

sphinx_gp_opengraph and sphinx_gp_sitemap are members of DEFAULT_EXTENSIONS, so every project that calls merge_sphinx_config() loads them automatically. Passing docs_url= is the only step required for default SEO emission — gp-sphinx fills in the upstream config keys both extensions need. Per-package details live on the sphinx-gp-opengraph and sphinx-gp-sitemap pages.

Live example

This site is built with gp-sphinx, using the same integration pattern shown above. See docs/conf.py for the exact coordinator call.

Copyable config snippet

extensions = [
    "gp_sphinx.config",
]

Public surface

This package is a coordinator rather than a Sphinx extension module. Its public runtime surface is documented in Configuration and API Reference.

Source on GitHub · PyPI