Quickstart¶

Installation¶

For latest official version:

$ pip install --user gp-sphinx

Upgrading:

$ pip install --user --upgrade gp-sphinx

Developmental releases¶

New versions of gp-sphinx are published to PyPI as alpha, beta, or release candidates. In their versions you will see notification like a1, b1, and rc1, respectively. 1.0.0b4 would mean the 4th beta release of 1.0.0 before general availability.

pip:

$ pip install --user --upgrade --pre gp-sphinx

pipx:

$ pipx install --suffix=@next 'gp-sphinx' --pip-args '\--pre' --force

uv:
```
$ uv add gp-sphinx --prerelease allow
```

via trunk (can break easily):

pip:

$ pip install --user -e git+https://github.com/git-pull/gp-sphinx.git#egg=gp-sphinx

uv:

$ uv add gp-sphinx --from git+https://github.com/git-pull/gp-sphinx.git

Usage¶

In your project’s docs/conf.py:

"""Sphinx configuration for my-project."""
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, Tony Narlock",
    source_repository="https://github.com/git-pull/my-project/",
    intersphinx_mapping={
        "py": ("https://docs.python.org/", None),
    },
)
globals().update(conf)

Adding extra extensions¶

conf = merge_sphinx_config(
    # ...
    extra_extensions=["sphinx_argparse_neo.exemplar", "sphinx_click"],
)

Removing default extensions¶

conf = merge_sphinx_config(
    # ...
    remove_extensions=["sphinx_design"],
)

Custom theme options¶

conf = merge_sphinx_config(
    # ...
    light_logo="img/my-logo.svg",
    dark_logo="img/my-logo-dark.svg",
    theme_options={"sidebar_hide_name": True},
)

Your first build¶

Create a docs directory with a static assets folder:

$ mkdir -p docs/_static

Create a minimal docs/index.md:

# My Project

Welcome to my project documentation.

Create docs/conf.py using the pattern from Usage above.

Build the HTML output:

$ uv run sphinx-build -b html docs docs/_build/html

Open docs/_build/html/index.html in your browser to see the result.