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

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