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

### 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)
- CSS classes and custom properties unified under a single `gp-sphinx-*`
  BEM namespace (retires the per-package `sab-`, `smf-`, `spf-`, `api-`,
  `gas-`, `gal-` prefixes and collapses their duplicate palettes) (#18)

### Features

- `sphinx-gp-theme`: dispatch `gp-sphinx:navigated` CustomEvent on
  `document` after every SPA-nav DOM swap. Third-party widgets that bind to
  swapped DOM can listen for this event to re-initialise after navigation
  without a full page reload. Payload: `event.detail.url` is the new URL.
- `sphinx-autodoc-fastmcp`: autodoc MCP prompts and resources end-to-end.
  Four new directives —
  ``{fastmcp-prompt}``, ``{fastmcp-prompt-input}``,
  ``{fastmcp-resource}``, ``{fastmcp-resource-template}`` — render the
  same card-style layout used for tools, with dedicated type badges
  (``prompt``, ``resource``, ``resource-template``) plus a MIME pill
  next to resources. A new ``fastmcp_server_module`` config value
  (``"pkg.server:mcp"``) points the collector at a live
  ``FastMCP`` instance; the collector reads
  ``local_provider._components`` directly and strips FastMCP's
  auto-appended ``"Provide as a JSON string matching the following
  schema: {...}"`` hint from prompt argument descriptions so docs
  read naturally. If the configured server hasn't run its registration
  hook yet, the collector calls ``register_all()`` / ``_register_all()``
  to populate the components.
- `sphinx-autodoc-fastmcp`: new Sphinx extension for FastMCP tool docs (card-style
  `desc` layouts, safety badges, MyST directives, cross-reference roles)
- `sphinx-ux-badges`: shared badge node (`BadgeNode`), builder API
  (`build_badge`, `build_badge_group`, `build_toolbar`), and base CSS
  layer shared by `sphinx-autodoc-fastmcp`, `sphinx-autodoc-api-style`,
  and `sphinx-autodoc-pytest-fixtures` (#13)
- `sphinx-ux-badges`: explicit size variants `xs` / `sm` / `lg` / `xl` via
  `build_badge(size=...)` and `BadgeNode(badge_size=...)` — compose with any
  fill, style, or color class (#13)
- Initial release of `gp_sphinx` shared documentation platform
- `merge_sphinx_config()` API for building complete Sphinx config from shared defaults
- Shared extension list, theme options, MyST config, font config
- Bundled workarounds (tabs.js removal, spa-nav.js injection)
- `sphinx-autodoc-pytest-fixtures`: Fixture tables now resolve `TypeAlias`
  return annotations — alias names are preserved and linked rather than
  expanding to the underlying union or generic type (#9)
- Integrated autodoc design system: twelve workspace packages in three
  tiers — shared infrastructure, domain autodocumenters, theme/coordinator —
  sharing one badge palette, one layout pipeline, and one typehint
  renderer (#18)
- New `sphinx-ux-autodoc-layout` package — componentized autodoc output
  with card containers, parameter folding, and managed signatures (#18)
- New `sphinx-autodoc-typehints-gp` package — single-package replacement
  for `sphinx-autodoc-typehints` + `sphinx.ext.napoleon`; resolves
  annotations statically at build time with no monkey-patching (#18)
- `sphinx-autodoc-argparse` now ships a real `argparse` Sphinx domain —
  `program` / `option` / `subcommand` / `positional` ObjTypes,
  `:argparse:*` xref roles, and two auto-generated indices
  (`argparse-programsindex`, `argparse-optionsindex`).
  `Framework :: Sphinx :: Domain` classifier added.  `:option:` /
  `std:cmdoption` continues to resolve for intersphinx consumers (#18)

### Bug fixes

- `sphinx-autodoc-fastmcp`: section labels for prompts and resources now
  use the typed `env.domains.standard_domain` accessor and route through the
  same direct-write pattern as `_transforms.register_tool_labels`. Resource
  and resource-template card labels carry the actual component name (e.g.
  ``my_resource``) rather than a slugified round-trip, so ``{ref}`` lookups
  resolve against the human-readable identifier (#21)
- `sphinx-autodoc-fastmcp`: the FastMCP register-all hook now fires whenever
  the resolved server exposes ``local_provider``, regardless of whether
  ``_components`` is already populated. Servers that register some components
  at module-import time (decorators) and others via an explicit
  ``register_all()`` previously dropped the deferred ones from autodoc (#21)
- `sphinx-autodoc-fastmcp`: narrow the ``except Exception`` around the optional
  ``fastmcp.*`` imports to ``except ImportError`` so unrelated runtime errors
  during fastmcp import propagate instead of producing silently empty docs
  (matches Sphinx's own ``sphinx.util.images`` pattern) (#21)
- `sphinx-autodoc-typehints-gp`: ``:exc:`~mod.Foo``` in ``Raises`` sections
  now renders as ``Foo`` (last-component shortener), matching Sphinx's
  ``PyXRefRole.process_link`` convention (#21)
- `sphinx-autodoc-typehints-gp`: ``Raises`` type fields split on commas only
  at bracket depth 0, keeping parameterised generics like ``Dict[str, X]``
  intact (#21)
- `sphinx-autodoc-typehints-gp`: empty ``Notes`` sections drop their rubric
  (intentional after ``.. todo::`` filtering); empty ``Examples``,
  ``References``, and other generic stub sections regain their rubric for
  legitimate stub usage (scoped via a new ``suppress_empty`` flag on
  ``_fmt_generic``) (#21)
- `sphinx-gp-theme`: SPA nav now scrolls to the target anchor on
  cross-page fragment links. `document.querySelector(hash)` mis-parses
  any hash containing `.` (e.g. Python autodoc IDs like
  `#libtmux_mcp.models.SearchPanesResult`) as a CSS class selector, so
  every `py:class` / `py:meth` / `py:attr` cross-ref was failing to
  scroll. Switched to `getElementById(decodeURIComponent(hash.slice(1)))`
  and moved the scroll-to-fragment branch out of the `!isPop` guard so
  browser forward/back also scrolls to fragments (#20)
- `sphinx-gp-theme`: SPA nav re-creates copy buttons from an inline
  template instead of cloning ``.copybtn`` from the initial page.
  Pages without code blocks (landing pages, prose-only indexes) left
  ``copyBtnTemplate`` null, so SPA-navigating to a code-block page
  produced no copy affordance. The inline template is byte-equivalent
  to sphinx-copybutton's output — same classes, same SVG with
  ``<title>Copy to clipboard</title>`` so screen readers announce the
  button correctly. `gp_sphinx` also injects a small
  ``window.GP_SPHINX_COPYBUTTON_SELECTOR`` bridge from the project's
  configured ``copybutton_selector`` via ``html-page-context``, so
  projects that extend the selector (e.g. prompt admonitions) get
  copy buttons re-applied to every configured match after SPA swap,
  not just to code blocks (#20)
- Load full weight range `[300, 400, 500, 600, 700]` for both IBM Plex
  Sans and IBM Plex Mono (badges render in monospace at `font-weight: 700`,
  Furo code blocks use 300, and intermediate weights inherit from
  surrounding context — previously only Sans had the full set)
- Replace `font-weight: 650` with `700` in badge CSS across
  `sphinx-autodoc-api-style`, `sphinx-autodoc-pytest-fixtures`,
  `sphinx-gp-theme`, and docs (650 is not a standard Fontsource weight,
  so browsers were synthesizing bold instead of using the real font file)
- Badge background colors, border colors, and dotted-underline tooltips lost
  after `BadgeNode` (`<span>`) replaced `<abbr>` in `sphinx-autodoc-api-style`
  and `sphinx-autodoc-pytest-fixtures`; restored via element-agnostic CSS
  selectors and correct fill defaults (#13)
- `sphinx-autodoc-argparse`: Namespace implicit section targets (`section["names"]`)
  by `id_prefix` in `render_usage_section`, `render_group_section`, and
  `_create_example_section` so multi-page docs that embed `.. argparse::` via
  MyST `{eval-rst}` no longer emit `duplicate label` warnings for `usage`,
  `options`, `positional arguments`, and cross-page `examples` targets (#16)

### Workspace packages

- `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 and subtle inset depth on
  solid pills (#13)
- `sphinx-autodoc-pytest-fixtures` — Sphinx autodocumenter for pytest fixtures.
  Registers `py:fixture` as a domain object type with `autofixture::` for
  single-fixture docs, `autofixtures::` for bulk module discovery, and
  `autofixture-index::` for summary tables. Fixtures render with scope/kind/autouse
  badges, classified dependency lists, reverse-dep tracking, and auto-generated
  usage snippets. Frozen dataclasses for pickle-safe incremental builds, parallel-safe,
  WCAG AA badge contrast, and pytest 9+ compatible.
  New: `auto-pytest-plugin` directive generates a standard pytest plugin page
  (install block, `pytest11` autodiscovery note, fixture summary and reference)
  from a single directive call. Optional `:project:`, `:summary:`, `:tests-url:`,
  and `:install-command:` options; body is free-form. Use `autofixture-index` +
  `autofixtures` directly when custom layout is needed.
- `sphinx-fonts` — Self-hosted web fonts via Fontsource CDN. Downloads at build time,
  caches locally, and injects `@font-face` CSS with preload hints and fallback
  font-metric overrides for zero-CLS loading.
- `sphinx-gp-theme` — Furo child theme for git-pull projects. Custom sidebar, footer
  icons, SPA navigation, and CSS variable-driven IBM Plex typography.
- `sphinx-autodoc-argparse` — Argparse CLI documentation extension with `.. argparse::`
  directive, epilog-to-section transformation, and Pygments lexers for argparse
  help/usage output.