CHANGES

# Changelog

To install the unreleased gp-sphinx version, see [developmental releases](https://gp-sphinx.git-pull.com/quickstart.html#developmental-releases).

[pip](https://pip.pypa.io/en/stable/):

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

[uv](https://docs.astral.sh/uv/):

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

## gp-sphinx 0.0.1 (unreleased)

<!-- To maintainers and contributors: Please add notes for the forthcoming version below -->

## gp-sphinx 0.0.1a10 (2026-04-25)

### Breaking changes

- Package renames: `sphinx-argparse-neo` → `sphinx-autodoc-argparse`,
  `sphinx-gptheme` → `sphinx-gp-theme`, `sphinx-autodoc-badges` →
  `sphinx-ux-badges`, `sphinx-autodoc-layout` → `sphinx-ux-autodoc-layout`,
  `sphinx-typehints-gp` → `sphinx-autodoc-typehints-gp` (#18)
- Sphinx floor bumped to 8.1 across the workspace (#18)
- All CSS classes and custom properties now live under the `gp-sphinx-*`
  namespace. Downstream stylesheets overriding the legacy `sab-`, `smf-`,
  `spf-`, `api-`, `gas-`, or `gal-` prefixes need to update their
  selectors. (#18)

### What's new

#### New package: `gp-sphinx`

Shared documentation platform for git-pull projects.
`merge_sphinx_config()` builds a complete Sphinx config from shared
defaults — extensions, theme, fonts, MyST, copybutton, rediraffe —
with per-project overrides. Bundles `tabs.js` removal and
`spa-nav.js` injection out of the box. (#5)

#### New package: `sphinx-gp-opengraph`

OpenGraph meta-tag emission. Drop-in for `sphinxext-opengraph`,
matplotlib-free; `ogp_social_cards` is accepted but ignored with a
warning. Replaces `sphinxext.opengraph` in `DEFAULT_EXTENSIONS`.
(#22)

#### New package: `sphinx-gp-sitemap`

`sitemap.xml` generator. Drop-in for `sphinx-sitemap`. Added to
`DEFAULT_EXTENSIONS`, so every gp-sphinx site emits one out of the
box. (#22)

#### New package: `sphinx-fonts`

Self-hosted web fonts via Fontsource CDN. Downloads at build time,
caches locally, and injects `@font-face` CSS with preload hints and
font-metric fallback overrides for zero-CLS loading. (#5)

#### New package: `sphinx-gp-theme`

Furo child theme for git-pull projects — custom sidebar, footer
icons, SPA navigation, and CSS variable-driven IBM Plex typography.
(#5)

#### New package: `sphinx-autodoc-argparse`

Argparse CLI documentation extension with `.. argparse::` directive,
epilog-to-section transformation, and Pygments lexers for argparse
help/usage output. (#5)

#### New package: `sphinx-autodoc-pytest-fixtures`

Sphinx autodocumenter for pytest fixtures. Renders fixtures as a
first-class domain object with scope / kind / autouse badges,
dependency tracking, and usage snippets. The `auto-pytest-plugin`
directive generates a complete plugin reference page from one call.
(#6, #8)

#### New package: `sphinx-ux-badges`

Shared badge node, builders, and base CSS for safety tiers, scope,
and kind labels. Extensions add color layers on top; TOC sidebar
shows compact badges with emoji icons. (#13)

#### New package: `sphinx-ux-autodoc-layout`

Componentized autodoc output — card containers, parameter folding,
managed signatures — used by every domain package in the workspace.
(#18)

#### New package: `sphinx-autodoc-typehints-gp`

Single-package replacement for `sphinx-autodoc-typehints` +
`sphinx.ext.napoleon`. Resolves annotations statically, so docs
builds stay deterministic across runs. (#18)

#### New package: `sphinx-autodoc-fastmcp`

Sphinx extension for FastMCP tool docs — card-style entries with
safety badges and cross-reference roles. Point
`fastmcp_server_module` at a live `FastMCP` instance to autodoc its
prompts, resources, and resource templates from the same surface
the server exposes. (#13, #21)

#### `gp-sphinx`: Integrated autodoc design system

Python APIs, pytest fixtures, Sphinx config values, docutils
directives, and FastMCP tools all render with one shared badge
palette and layout across the workspace. (#18)

#### `gp-sphinx`: SEO config auto-wired from `docs_url`

`merge_sphinx_config` auto-derives `ogp_site_url`, `ogp_site_name`,
`ogp_image`, `site_url`, and `sitemap_url_scheme` (flat `"{link}"`)
from a single `docs_url`. (#22)

#### `sphinx-autodoc-docutils`: Register-aware directive and role discovery

`autodirective-index`, `autodirectives`, `autorole-index`, and
`autoroles` accept an extension package name and surface each entry
under the name the package actually registers — so multi-word
directive class names render correctly instead of getting collapsed
to all-lowercase. (#22)

#### `sphinx-autodoc-argparse`: New `argparse` Sphinx domain

A real `argparse` Sphinx domain ships with `:argparse:program:` /
`:option:` / `:subcommand:` / `:positional:` cross-references and
two auto-generated indices. Existing `:option:` and `std:cmdoption`
consumers continue to resolve. (#18)

#### `sphinx-ux-badges`: Shared badge surface

Shared badge node, builders, and CSS adopted by
`sphinx-autodoc-fastmcp`, `sphinx-autodoc-api-style`, and
`sphinx-autodoc-pytest-fixtures`. Size variants (`xs` / `sm` / `lg`
/ `xl`) compose with any color or fill class. (#13)

#### `sphinx-autodoc-pytest-fixtures`: `TypeAlias` resolution

Fixture tables preserve and link `TypeAlias` return annotations
rather than expanding them to the underlying union or generic type.
(#9)

#### `sphinx-gp-theme`: `gp-sphinx:navigated` event after SPA nav

A `gp-sphinx:navigated` event fires on `document` after every
SPA-nav DOM swap, so third-party widgets can re-initialise without
a full page reload. The new URL is on `event.detail.url`. (#20)

### Bug fixes

#### `sphinx-gp-opengraph`: XHTML self-closing void tags no longer drop trailing title text

Titles containing XHTML-style void elements (`<br/>`, `<img/>`,
`<hr/>`) keep every text chunk after the void element. Previously
`og:title` lost everything past the first such tag. (#22)

#### `sphinx-gp-opengraph`: HTML-escape every meta-tag attribute

Titles, site names, image alts, and custom field-list values
containing `&`, `<`, `>`, `"`, or `'` reach the page head as HTML
entities. Previously a project named `AT&T` emitted invalid
attribute markup. (#22)

#### `gp-sphinx`: Preserve `docs_url` path component in derived URLs

Sites hosted at a path (e.g. `docs_url="https://example.org/docs"`)
emit correct Open Graph canonical URLs and image URLs. The
trailing-slash normalisation that already covered `site_url` now
also covers `ogp_site_url`. (#22)

#### `sphinx-gp-sitemap`: Complete sitemap on incremental and parallel builds

Incremental builds (where Sphinx writes only the changed page) and
parallel builds (`sphinx-build -j N`) emit a complete sitemap. URLs
also match the `<a href>` paths the HTML builder emits — so sites
that set `html_link_suffix` or have spaces in pagenames no longer
get divergent sitemap links. (#22)

#### `sphinx-autodoc-docutils`: Surface failed `setup()` replay in build log

Extensions whose `setup()` raises during autodoc discovery now
leave a DEBUG breadcrumb in the build log instead of silently
emitting incorrect directive or role names. (#22)

#### `sphinx-autodoc-fastmcp`: Section labels resolve by component name

Prompt and resource card labels carry the actual component name
(e.g. `my_resource`), so `{ref}` lookups resolve against the
human-readable identifier. (#21)

#### `sphinx-autodoc-fastmcp`: Decorator-registered components no longer dropped

FastMCP servers that mix decorator-time registration with explicit
`register_all()` calls now appear fully in autodoc. Previously the
decorator-only paths were silently skipped. (#21)

#### `sphinx-autodoc-fastmcp`: Surface real import failures

Runtime errors during the fastmcp module import now propagate
instead of being swallowed and producing silently empty docs.
(#21)

#### `sphinx-autodoc-typehints-gp`: `:exc:` references with `~mod.Foo` shorten to `Foo`

Exception cross-refs written as `~mod.Foo` render as just `Foo`,
matching the abbreviated form used elsewhere in the typehint
renderer. (#21)

#### `sphinx-autodoc-typehints-gp`: `Raises` type fields preserve parameterised generics

`Raises` fields no longer split parameterised generics like
`Dict[str, X]` on the inner comma. Multi-type `Raises` lines still
split on commas between exception types as before. (#21)

#### `sphinx-autodoc-typehints-gp`: Empty `Examples` / `References` sections render their rubric

Empty `Examples` and `References` sections — common in legitimate
stubs — display their rubric. Empty `Notes` sections still drop
theirs. (#21)

#### `sphinx-gp-theme`: SPA nav scrolls to anchor on cross-page fragments

Cross-page Python autodoc anchors (e.g.
`#libtmux_mcp.models.SearchPanesResult`) now scroll into view after
SPA navigation, including via browser back/forward. (#20)

#### `sphinx-gp-theme`: Copy buttons survive SPA navigation

Code-block pages reached via SPA navigation show the copy affordance
even on builds where the entry page had no code blocks. Projects
that extend `copybutton_selector` (e.g. prompt admonitions) opt
their custom selectors into the same re-application via
`window.GP_SPHINX_COPYBUTTON_SELECTOR`. (#20)

#### `sphinx-fonts`: Full weight range for IBM Plex Sans and Mono

IBM Plex Sans and Mono load weights 300–700, so badges and code
blocks render in the real font weight instead of a browser-
synthesised approximation. (#11, #12)

#### `sphinx-ux-badges`: Restore background, border, and tooltip styling

Badges in `sphinx-autodoc-api-style` and
`sphinx-autodoc-pytest-fixtures` regain their background, border,
and tooltip — visual treatment that regressed when the underlying
badge node changed. (#13)

#### `sphinx-autodoc-argparse`: No more `duplicate label` warnings on multi-page docs

Multi-page docs that embed `.. argparse::` via MyST `{eval-rst}`
build cleanly. Section IDs are now namespaced per program so
`usage`, `options`, and friends no longer collide across pages.
(#16)