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.1a21 (unreleased)

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

## gp-sphinx 0.0.1a20 (2026-05-17)

gp-sphinx 0.0.1a20 closes a Largest-Contentful-Paint regression on
the sidebar logo across every consumer docs site. Web-Vitals reports
recorded LCP timings of 2.7 to 6.7 seconds because the bundled theme
emitted a `<link rel="prefetch" as="image">` hint for the logo URLs
instead of a `<link rel="preload" as="image" fetchpriority="high">`;
the prefetch directive is reserved for future-navigation hints that
browsers defer to idle. Switching the directive to `preload` plus
`fetchpriority="high"` promotes the logo to the same critical-path
priority the bundled fonts already use.

### Fixes

#### Sidebar logo loads as a critical-path resource

Sidebar logos were the Largest Contentful Paint element on every
consumer docs site with timings of 2.7 to 6.7 seconds. The
`gp-furo-theme` template emitted `<link rel="prefetch">` hints for
the logo URLs — a low-priority "future navigation" directive that
browsers defer until idle — even though the logo sits above the
fold on first paint. The fix switches the directive to
`<link rel="preload" as="image" fetchpriority="high">`, mirroring
the pattern already used for the bundled font preloads, and adds a
matching `fetchpriority="high"` attribute to the `<img>` tag.

Cumulative Layout Shift was already zero on these sites — the
`<img>` carries `width="200" height="200"` so the browser reserves
the 200×200 box before bytes arrive. As belt-and-suspenders for any
consumer using `gp-furo-theme` standalone (without
`sphinx-gp-theme`'s overlay), the `.sidebar-logo-container` CSS
gains `aspect-ratio: 1 / 1` and `.sidebar-logo` gains
`height: auto`, so the box reserves the same square regardless of
whether the HTML attrs make it through theme customisations. (#40)

### Documentation

#### Visual identity for the gp-sphinx docs site

The gp-sphinx docs site at <https://gp-sphinx.git-pull.com/> now
ships the standard tony/* logo, favicon, and PWA icon set. The Furo
sidebar shows light and dark logo variants, the browser tab carries
a proper favicon, and a web-app manifest advertises the icon sizes
for Android, Apple, and Microsoft platforms. (#41)

## gp-sphinx 0.0.1a19 (2026-05-17)

gp-sphinx 0.0.1a19 closes the gap on Cloudflare Rocket Loader
compatibility by annotating every inline `<script>` block the bundled
theme templates emit with `data-cfasync="false"`. The fix is
invisible when Rocket Loader is off; with it on, the sidebar projects
section stops blank-flashing on navigation, Furo's body theme
bootstrap script runs synchronously as designed, and the Python
module index stays collapsed on the first frame.

### Fixes

#### Cloudflare Rocket Loader compatibility on bundled theme scripts

Three inline `<script>` blocks in the bundled theme templates lacked
the `data-cfasync="false"` opt-out: the `sphinx-gp-theme`
sidebar-projects active-link toggle, Furo's body no-flicker theme
bootstrap (`gp-furo-theme`), and the Python `genindex`
`COLLAPSE_INDEX` setter (`gp-furo-theme`). With Rocket Loader
enabled by a consumer's CDN configuration, these scripts would run
too late and produce visible artifacts — a brief blank flash in the
sidebar projects section, a flash-of-wrong-theme during the body
bootstrap window, and an expanded `genindex` on first paint. Each
script now carries the same opt-out the two flash-of-wrong-theme
prevention scripts in `gp_sphinx/config.py` already use. A local
copy of the sidebar projects template in this repository's
`docs/_templates/sidebar/projects.html` is synced so the workspace's
own site renders the fix on every build. (#39)

## gp-sphinx 0.0.1a18 (2026-05-10)

gp-sphinx 0.0.1a18 ships curated autodoc rendering across the docs
surface. Parameter signatures now resolve default values to their
source text — including dataclass `__init__` synthetic defaults,
sentinel constants by name, and identifier defaults wired up as
live cross-references to their documented class. Type expressions
in autodoc field lists route through the same xref pipeline so
links and chip styling stay consistent with the signature.

The autodoc layout adapts to narrow viewports with a dual-variant
header: below 52rem the header row stacks instead of squeezing, and
below 30rem long signatures scroll horizontally instead of wrapping
mid-identifier. A new `gp-sphinx` cascade layer makes workspace
overrides win over Furo declaratively, and parameter and field-list
typography unify into a single metadata-sized band.

A workspace-wide `linkcode_resolve` factory now covers every
uv/pnpm monorepo package with one registration, pointing at the
configured live tip branch rather than per-package version tags.

### What's new

#### `gp-sphinx`: Curated default-value rendering for autodoc

`autodoc_preserve_defaults=True` is now the workspace default, and a
new listener fills the synthetic `__init__` gap so dataclass
parameters render as `=[]` instead of `=<factory>`, and sentinel
constants render as their source name (e.g.
`scope=DEFAULT_OPTION_SCOPE`) instead of `<...object at 0x...>`.
Long `:value:` text is collapsed so multi-KB constants no longer
dominate API pages while short useful values stay intact.
Identifier defaults inside parameter signatures become live
cross-references to their documented class — the resulting HTML
matches an inline `:py:class:` role, so hand-written
`.. py:function::` directives benefit too. (#36)

#### `sphinx-autodoc-typehints-gp`: Canonical Python xrefs in field lists

Type expressions in autodoc field lists route through the same
xref pipeline as the signature, so links resolve consistently and
nested types render with chip styling that matches the rest of the
page. (#36)

#### Autodoc typography polish across the docs surface

Parameter and field-list rows share a unified metadata-sized
typography band across the autodoc stack. Code chips sit flush
against generic-type brackets, parameter names use sans-bold while
monospace is reserved for code identifiers, and root-level scaling
on wide viewports follows a `clamp()` ramp instead of stepping up
at a single breakpoint. A new `gp-sphinx` cascade layer makes
workspace overrides win over Furo declaratively rather than via
unlayered precedence. (#36)

#### `gp-sphinx`: Workspace-wide `linkcode_resolve` factory

`make_workspace_linkcode_resolve()` is a drop-in `linkcode_resolve`
for uv/pnpm monorepos — one registration covers every package under
`packages/` by computing GitHub URLs relative to a `repo_root`. The
generated URLs always point at a single configurable branch
(default `main`), since workspace packages carry independent
versions while the docs site tracks live tip. (#36)

#### `sphinx-ux-autodoc-layout`: Responsive autodoc headers on narrow viewports

Below 52rem the header row stacks instead of squeezing, with the
type badge pinned beside the signature and the source link
right-anchored in its toolbar. Below 30rem long signatures scroll
horizontally rather than wrapping mid-identifier, and the permalink
reveals on tap for touch users. (#36)

### Bug fixes

#### `sphinx-gp-theme`: TOC font-size override now applies

The override for `--toc-font-size` and `--toc-title-font-size` was
inert because `gp-furo-tokens` emits the default values on `body`,
not `:root`. The sidebar TOC now picks up the configured larger
size. (#36)

#### `sphinx-ux-autodoc-layout`: Mobile header keeps the type badge beside the signature

On narrow viewports the type badge previously wrapped below the
signature, breaking the eyebrow-style layout. It now stays pinned
to the left of the signature row. (#36)

#### `sphinx-vite-builder`: CI setup hint no longer requires a root lockfile

The recipe printed by `PnpmMissingError` (and the matching
README/AGENTS samples) used to include `cache: pnpm`, which fails
on consumer CI with "Dependencies lock file is not found" when the
consumer repo has no root `pnpm-lock.yaml`. The hint now omits that
line, with a note explaining when it is safe to add back. (#36)

## gp-sphinx 0.0.1a17 (2026-05-09)

### What's new

#### `gp-sphinx`: Default font-preload list now covers heading, italic, and bold-code FOUT

`DEFAULT_SPHINX_FONT_PRELOAD` adds IBM Plex Sans 500 / 600 normal
(`h1`–`h6` and `blockquote.epigraph`), Sans 400 italic (`<em>` body
text and announcement bars), and Mono 700 normal (bold inline code).
Downstream consumers that render those surfaces no longer need a
local `sphinx_font_preload` override to avoid first-paint FOUT.
(#34)

### Bug fixes

#### `gp-sphinx`: MystLexer highlights `:::{directive}` colon-fences

Embedded MyST snippets that use the colon-fence directive syntax now
tokenize correctly when rendered through `pygments` (e.g. inside
`.. code-block:: myst`). Previously the fence and body fell through
to plain text. (#33)

### Documentation

#### Per-package documentation tree

Workspace packages now ship per-package directories with Diátaxis
subpages (`tutorial`, `how-to`, `reference`, `explanation`,
`examples`); the sidebar nests subpages under their package. New
`{package-landing}` and `{cluster-toctree}` directives derive
landings and sidebar leaves from a `PackageDocsRecord` schema that
reads both `pyproject.toml` and `package.json` manifests, so JS-only
packages like `@gp-sphinx/furo-tokens` sit alongside the Python
ones. Legacy `/packages/<name>.html` URLs continue to resolve. (#33)

#### Showcase opt-in directives

`{live-signature}`, `{package-kitchen-sink}`, `{surface-changelog}`,
and `{package-dependents}` opt in via
`[tool.gp-sphinx.docs].showcase` for richer per-package landings.
(#33)

## gp-sphinx 0.0.1a16 (2026-05-03)

### What's new

#### New package: `sphinx-vite-builder`

PEP 517 backend, hatchling build hook (`[tool.hatch.build.hooks.vite]`),
and Sphinx extension that orchestrate Vite via pnpm. Wheels ship with
the static tree pre-baked; source builds error loudly when pnpm or
Node isn't on PATH, with copy-pasteable CI setup recipes for GitHub
Actions, CircleCI, Azure Pipelines, and GitLab CI inlined into the
error. `SPHINX_VITE_BUILDER_SKIP=1` short-circuits the orchestration
when an external pipeline owns Vite. Replaces and supersedes
`gp-sphinx-vite`; `merge_sphinx_config(vite_orchestration=True)`
auto-injects the new extension. (#29)

### Bug fixes

#### `gp-furo-theme`: Wheels now ship with vite-built CSS and JS

`0.0.1a15` published wheels with an empty `static/` tree, leaving
docs sites across every consumer unstyled. The new
`sphinx-vite-builder.build` backend runs Vite at release time and
hatchling packs the resulting assets, so a `pip install` from PyPI
gets styled docs without the consumer rebuilding assets locally. (#29)

## gp-sphinx 0.0.1a15 (2026-05-02)

### What's new

#### Theme: workspace-owned port of [Furo]

`sphinx-gp-theme` now inherits from `gp-furo`, a workspace-owned port
of @pradyunsg's [Furo] authored in pure Tailwind v4. [Furo] and its
transitive dependencies (`accessible-pygments`, `sphinx-basic-ng`) no
longer install with gp-sphinx. The CSS custom-property contract is
preserved — existing `light_css_variables` / `dark_css_variables`
overrides keep working and rendering is visually equivalent. (#25)

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

Standalone [Furo]-equivalent Sphinx theme. Available without the
gp-sphinx project layer for users who want [Furo]-style rendering on
its own. (#25)

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

Transparent Vite + pnpm orchestration for theme asset compilation.
No-op in production builds; activates under `sphinx-autobuild` to
provide live CSS/JS rebuilds during authoring. The package page
also documents justfile and Makefile recipes for wiring `just build`
/ `make build` to run vite before plain `sphinx-build`. (#25, #26)

## gp-sphinx 0.0.1a14 (2026-05-02)

### Bug fixes

#### `sphinx-gp-theme`: Light-mode shell prompts and command output now visually distinct

The `gp-sphinx-light` Pygments style now colors `Generic.Prompt` purple
and `Generic.Output` cyan so they stand out from surrounding text.
Previously both fell through to a generic slate, leaving prompts and
command output indistinguishable from section sub-headings — mirrors
the dark-mode (monokai) pink + cyan pairing.

## gp-sphinx 0.0.1a13 (2026-04-30)

### What's new

#### `sphinx-gp-theme`: Light-mode code blocks now render with a light palette

Light mode previously fell back to monokai-on-light because both
Furo Pygments slots defaulted to monokai. The theme now ships
`gp-sphinx-light` (a CodeMirror-derived light palette) and pairs it
with monokai under `body[data-theme="dark"]`, so both modes pick up
appropriate code-block colors out of the box. (#24)

### Bug fixes

#### `sphinx-gp-theme`: argparse directives now follow the active theme

`.. argparse::` blocks hardcoded a One Dark palette and rendered
dark-on-light in light mode. Token colors now flow through
`--gp-sphinx-argparse-*` custom properties with light defaults and
dark overrides scoped to `body[data-theme="dark"]`. (#24)

## gp-sphinx 0.0.1a12 (2026-04-27)

### Bug fixes

#### `sphinx-gp-theme`: Sidebar logo no longer disappears on iOS Safari during navigation

Fixed a glitch where the logo would blank out when navigating between
pages on iOS Safari.

## gp-sphinx 0.0.1a11 (2026-04-26)

### Bug fixes

#### `gp-sphinx`: No more theme flicker on initial load or toggle

The light/dark theme applies cleanly on every page: no flash of the
wrong scheme on initial load, no toggle-icon "pop-in" mid-load, and
no animated mid-blend when toggling at runtime. (#23)

## 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)

[Furo]: https://github.com/pradyunsg/furo