Changelog¶
To install the unreleased gp-sphinx version, see developmental releases.
pip:
$ pip install --user --upgrade --pre gp-sphinx
uv:
$ uv add gp-sphinx --prerelease allow
gp-sphinx 0.0.1a27 (unreleased)¶
gp-sphinx 0.0.1a26 (2026-05-25)¶
Fixes¶
Footer (source path, machine-readable links, next/prev) now updates on SPA navigation instead of staying stale from the initial page load.
gp-sphinx 0.0.1a25 (2026-05-25)¶
Fixes¶
Add
sphinx-gp-llmstogp-sphinxruntime dependencies so consumer projects get it automatically when installinggp-sphinx.
gp-sphinx 0.0.1a24 (2026-05-25)¶
gp-sphinx 0.0.1a24 ships LLM-friendly documentation outputs for every
consumer docs site. A new extension generates llms.txt,
llms-full.txt, docs.json, and per-page .md twins during the
standard HTML build, following conventions from llmstxt.org,
Cloudflare, Anthropic, and Lakebed. The page footer links all
machine-readable formats alongside the existing raw-source link.
What’s new¶
LLM-friendly documentation outputs¶
New workspace package sphinx-gp-llms generates four output formats
during the standard HTML Sphinx build: llms.txt (structured Markdown
index per the llmstxt.org spec), llms-full.txt
(concatenated full-content Markdown), docs.json (agent-oriented
manifest with per-page headings), and per-page .md twin files. Added
to DEFAULT_EXTENSIONS so all consumer
projects get LLM outputs automatically when docs_url is configured.
The footer’s “Machine-readable” line links every enabled format. (#47)
autoconfigvalues :exclude: option¶
The autoconfigvalues directive now accepts an :exclude: option to
skip specific config values from the rendered output — useful when two
extensions register the same value and Sphinx warns on the duplicate
confval. (#48)
gp-sphinx 0.0.1a23 (2026-05-24)¶
gp-sphinx 0.0.1a22 (2026-05-24)¶
Fixes¶
sphinx-ux-autodoc-layout: Anchor targets scroll to viewport top, not center¶
Hash navigation positioned the target element in the middle of the
viewport instead of near the top, overriding the theme’s
scroll-margin-top rules. (#45)
gp-sphinx 0.0.1a21 (2026-05-23)¶
Fixes¶
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¶
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¶
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)All CSS classes and custom properties now live under the
gp-sphinx-*namespace. Downstream stylesheets overriding the legacysab-,smf-,spf-,api-,gas-, orgal-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-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)
Bug fixes¶
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-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)