pkg(workspace): add sphinx-vite-builder, retire gp-sphinx-vite (#29)

A new `sphinx-vite-builder` package consolidates the workspace's Vite
story into one place with three orthogonal activation paths sharing
one async-subprocess core: a PEP 517 build backend, a hatchling build
hook, and a Sphinx extension. Replaces `gp-sphinx-vite` (deleted) and
fixes the `0.0.1a15` regression where `gp-furo-theme` published
wheels with an empty `static/` tree, leaving docs sites unstyled.

The whole product is the wheel-vs-source asymmetry: a `web/`
directory triggers strict orchestration with fast-fail diagnostics
(`PnpmMissingError`, `NodeModulesInstallError`, `ViteFailedError`,
each carrying a copy-pasteable hint); an absent `web/` (the
unpacked-sdist case) short-circuits cleanly so wheels published to
PyPI need zero toolchain on the consumer side. Errors are
self-healing in CI — detected providers (GitHub Actions, CircleCI,
Azure Pipelines, GitLab CI) get the right setup recipe inlined into
the error message.

**New package — three activation paths:**

- **PEP 517 backend** at `sphinx_vite_builder.build`. Drop-in for
  `hatchling.build`; runs `pnpm exec vite build` before delegating
  wheel/sdist construction.
- **Hatchling build hook** at `[tool.hatch.build.hooks.vite]`. Same
  orchestration via hatchling's plugin system; composes with other
  hatchling hooks.
- **Sphinx extension** registered by `setup()`. One-shot vite build
  under `sphinx-build`; long-running `vite build --watch` under
  `sphinx-autobuild` with graceful SIGTERM→SIGKILL teardown via
  `os.killpg` on the POSIX session group.

**Bug fix — `gp-furo-theme` wheels now ship vite-built CSS and JS.**
`0.0.1a15` published wheels with an empty `static/` because
hatchling's `force-include` rejected the gitignored Vite output;
`sphinx-build` then silently skipped the missing entries. The
backend now builds assets at release time and hatchling packs them
via `[tool.hatch.build] artifacts`.

**Workspace migration.** Consumers using
`merge_sphinx_config(vite_orchestration=True)` continue to work
unchanged — the auto-injection points at `sphinx_vite_builder` now.
Power users with raw `extensions = ["gp_sphinx_vite"]` or
`gp_sphinx_vite_root = ...` in `conf.py` rename to
`sphinx_vite_builder` / `sphinx_vite_builder_root`.

**Released as `0.0.1a16.dev4`.** All workspace packages bumped in
lockstep; `gp-sphinx-vite` retired (issue #32 tracks the manual PyPI
yank).

**Cross-repo validation.** Production deploys verified live across
the consumer corpus — `cihai.git-pull.com`, `libtmux.git-pull.com`,
`tmuxp.git-pull.com`, `vcspull.git-pull.com` and 6 others all serve
the new theme assets (curl against `_static/styles/furo-tw.css`
returns 200 across the board, fixing the `a15` 404 regression).

Breaking changes:
- `gp-sphinx-vite` package retired. Workspace consumers via
  `merge_sphinx_config(vite_orchestration=True)` are unaffected;
  hand-rolled `extensions = ["gp_sphinx_vite"]` callers must rename
  to `"sphinx_vite_builder"`. Config keys renamed:
  `gp_sphinx_vite_{mode,root}` → `sphinx_vite_builder_{mode,root}`.

Closes #28. Closes #30 (Phase 2). Closes #31 (Phase 3). Tracks #32
for the manual PyPI yank.

See also:
- Cross-repo integration: tmux-python/libtmux-mcp#33
- Consumer rollout: cihai/cihai#399, cihai/cihai-cli#348,
  cihai/unihan-db#364, cihai/unihan-etl#356, vcs-python/vcspull#547,
  vcs-python/libvcs#526, vcs-python/g#55, git-pull/gp-libs#69,
  tmux-python/libtmux#666, tmux-python/tmuxp#1037
- maturin (Rust+Cargo analog): https://github.com/PyO3/maturin
- sphinx-theme-builder (webpack analog): https://github.com/pradyunsg/sphinx-theme-builder

Author: tony

.github/workflows/release.yml

@@ -42,6 +42,25 @@ jobs:
               print(f"{key}={value}")
           PY
 
+      # `gp-furo-theme`'s build backend (`sphinx_vite_builder.build`)
+      # runs `pnpm exec vite build` during sdist + wheel construction.
+      # Without pnpm + Node the backend fast-fails with PnpmMissingError
+      # and the release pipeline aborts before publish — exactly the
+      # invariant we want, but it requires the toolchain to be set up
+      # first. The backend short-circuits cleanly inside the unpacked
+      # sdist (no `web/` → assume pre-baked) so end users `pip install`
+      # without pnpm/Node.
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
       - name: Install workspace dependencies
         run: uv sync --all-packages --all-extras --group dev
 

.github/workflows/tests.yml

@@ -7,6 +7,17 @@ on:
 jobs:
   qa:
     runs-on: ubuntu-latest
+    # `gp-furo-theme`'s build backend (`sphinx_vite_builder.build`) runs
+    # `pnpm exec vite build` during editable installs, which the qa
+    # runners can't satisfy (no pnpm/Node). qa's purpose is lint/types/
+    # tests against Python sources — the rendered theme isn't exercised
+    # here — so we set the documented escape-hatch env var on the whole
+    # job. The backend then short-circuits and the install succeeds.
+    # Test suites that build a Sphinx project with html_theme="gp-furo"
+    # behave the same as they do on a stock checkout without vite —
+    # Sphinx silently skips the missing static entries (no -W in qa).
+    env:
+      SPHINX_VITE_BUILDER_SKIP: "1"
     strategy:
       fail-fast: false
       matrix:
@@ -75,6 +86,21 @@ jobs:
         with:
           enable-cache: true
 
+      # `gp-furo-theme`'s build backend (`sphinx_vite_builder.build`)
+      # runs vite during editable install, populating the gitignored
+      # `static/` tree so the docs build below picks up real CSS / JS.
+      # The pnpm/Node steps below give the backend a working toolchain.
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
       - name: Install workspace dependencies
         run: uv sync --all-packages --all-extras --group dev
 
@@ -97,6 +123,25 @@ jobs:
         with:
           enable-cache: true
 
+      # `gp-furo-theme`'s sdist + wheel both go through
+      # `sphinx_vite_builder.build`, which runs vite. The wheels
+      # produced here are consumed by the smoke matrix below — they
+      # MUST contain populated `static/`, otherwise downstream smoke
+      # installs render unstyled. pnpm + Node satisfy that toolchain
+      # requirement; the backend's wheel-from-sdist short-circuit
+      # (no `web/` in unpacked sdist → assume pre-baked) means smoke
+      # jobs themselves don't need this setup.
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
       - name: Install workspace dependencies
         run: uv sync --all-packages --all-extras --group dev
 
@@ -135,6 +180,7 @@ jobs:
           - sphinx-autodoc-typehints-gp
           - sphinx-ux-badges
           - sphinx-ux-autodoc-layout
+          - sphinx-vite-builder
     steps:
       - uses: actions/checkout@v6
 
@@ -157,6 +203,12 @@ jobs:
 
       - name: Smoke test root bootstrap install
         if: matrix.target == 'root-install'
+        # The root install transitively builds `gp-furo-theme`, which
+        # routes through `sphinx_vite_builder.build`. The smoke target
+        # only verifies that imports resolve — it doesn't exercise the
+        # rendered theme — so we skip the vite invocation.
+        env:
+          SPHINX_VITE_BUILDER_SKIP: "1"
         run: python scripts/ci/package_tools.py smoke root-install
 
       - name: Smoke test built package artifact

CHANGES

@@ -18,6 +18,30 @@ $ uv add gp-sphinx --prerelease allow
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
+### 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

README.md

@@ -1,8 +1,8 @@
 # gp-sphinx · [![Python Package](https://img.shields.io/pypi/v/gp-sphinx.svg)](https://pypi.org/project/gp-sphinx/) [![License](https://img.shields.io/github/license/git-pull/gp-sphinx.svg)](https://github.com/git-pull/gp-sphinx/blob/main/LICENSE)
 
-Integrated autodoc design system for Sphinx.  Twelve packages in three tiers
-that replace ~300 lines of duplicated `docs/conf.py` with ~10 lines and
-produce beautiful, consistent API documentation.
+An integrated autodoc design system for Sphinx that replaces ~300 lines
+of duplicated `docs/conf.py` with ~10 lines and produces beautiful,
+consistent API documentation.
 
 ## Requirements
 
@@ -50,21 +50,25 @@ Out of the box, `merge_sphinx_config()` activates:
 - **Componentized layouts** (`sphinx-ux-autodoc-layout`) — card containers, parameter folding, managed signatures
 - **Clean type hints** (`sphinx-autodoc-typehints-gp`) — simplified annotations with cross-referenced links, replacing `sphinx-autodoc-typehints` and `sphinx.ext.napoleon`
 - **Unified badge system** (`sphinx-ux-badges`) — type and modifier badges with a shared colour palette
-- **Six domain autodocumenters** — Python API, argparse CLIs, pytest fixtures, FastMCP tools, docutils directives, Sphinx config values
+- **Autodoc extensions** — Python API, argparse CLIs, pytest fixtures, FastMCP tools, docutils directives, Sphinx config values
 - **IBM Plex fonts** via Fontsource with preloaded web fonts
 - **Full dark mode** theming via CSS custom properties
 
 See the [Gallery](https://gp-sphinx.git-pull.com/gallery.html) for live demos of every component.
 
-## Three-tier architecture
+## Workspace architecture
 
-The workspace is organized into three tiers — lower layers never depend on higher ones:
+Lower layers never depend on higher ones:
 
-- **Shared infrastructure**: `sphinx-ux-badges`, `sphinx-ux-autodoc-layout`, `sphinx-autodoc-typehints-gp`
-- **Domain packages**: `sphinx-autodoc-api-style`, `sphinx-autodoc-docutils`, `sphinx-autodoc-fastmcp`, `sphinx-autodoc-pytest-fixtures`, `sphinx-autodoc-sphinx`
-- **Theme and coordinator**: `gp-sphinx`, `sphinx-gp-theme`, `sphinx-fonts`, `sphinx-autodoc-argparse`
+- **Common libraries** — `sphinx-ux-badges`, `sphinx-ux-autodoc-layout`, `sphinx-autodoc-typehints-gp`, `sphinx-fonts`
+- **Autodoc extensions** — `sphinx-autodoc-api-style`, `sphinx-autodoc-argparse`, `sphinx-autodoc-docutils`, `sphinx-autodoc-fastmcp`, `sphinx-autodoc-pytest-fixtures`, `sphinx-autodoc-sphinx`
+- **Build utils** — `sphinx-vite-builder` ([PEP 517](https://peps.python.org/pep-0517/) backend + hatchling build hook + Sphinx extension that runs Vite via pnpm; publishable to PyPI for use outside this workspace)
+- **Theme and coordinator** — `gp-sphinx`, `sphinx-gp-theme`, `gp-furo-theme`
+- **SEO** — `sphinx-gp-opengraph`, `sphinx-gp-sitemap` (auto-loaded by `gp-sphinx` when `docs_url` is set)
 
-See the [Architecture](https://gp-sphinx.git-pull.com/architecture.html) page for the full package map.
+See the [Architecture](https://gp-sphinx.git-pull.com/architecture.html)
+and [Packages](https://gp-sphinx.git-pull.com/packages/) pages for the
+full package map; the docs site auto-enumerates as the workspace grows.
 
 ## More information
 

docs/_ext/package_reference.py

@@ -38,7 +38,7 @@
 >>> package = workspace_packages()[0]
 >>> package["name"] in {
 ...     "gp-furo-theme",
-...     "gp-sphinx-vite",
+...     "sphinx-vite-builder",
 ...     "sphinx-gp-opengraph",
 ...     "sphinx-gp-sitemap",
 ...     "gp-sphinx",

docs/architecture.md

@@ -2,17 +2,17 @@
 
 # Architecture
 
-Twelve workspace packages in three tiers.  Lower layers never depend on
-higher ones — domain packages consume shared infrastructure, and the
+Workspace packages organized in tiers.  Lower layers never depend on
+higher ones — autodoc extensions consume shared infrastructure, and the
 presentation layer wires everything together for downstream projects.
 
-The sidebar groups these twelve packages into four navigation buckets
-(Domain Packages, UX, Utils, Internal) — a reader-facing grouping that
-is orthogonal to the dependency-ordered tier map below.
+The sidebar groups these packages into navigation buckets (Domain Packages,
+UX, Utils, Internal) — a reader-facing grouping that is orthogonal to the
+dependency-ordered tier map below.
 
 ## Tier 1: Shared infrastructure
 
-The rendering pipeline that all domain packages consume:
+The rendering pipeline that every autodoc extension consumes:
 
 ::::{grid} 1 1 3 3
 :gutter: 2
@@ -43,39 +43,121 @@ Replaces `sphinx-autodoc-typehints` + `sphinx.ext.napoleon`.
 
 ::::
 
-## Tier 2: Domain packages
+## Tier 2: Autodoc extensions
 
-Domain-specific autodoc extensions that consume Tier 1 and add
-project-specific rendering logic:
+Domain-specific [autodoc extensions](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
+that consume Tier 1 and add project-specific rendering logic. Each
+ships directives that generate documentation from a particular
+source-construct family:
 
-| Package | Domain | Directives |
-|---------|--------|------------|
-| {doc}`sphinx-autodoc-api-style <packages/sphinx-autodoc-api-style>` | Standard Python | `autofunction`, `autoclass`, `automodule` |
-| {doc}`sphinx-autodoc-argparse <packages/sphinx-autodoc-argparse>` | Custom `argparse` domain — programs, options, subcommands, positionals | `argparse` |
-| {doc}`sphinx-autodoc-docutils <packages/sphinx-autodoc-docutils>` | docutils | `autodirective`, `autorole` |
-| {doc}`sphinx-autodoc-fastmcp <packages/sphinx-autodoc-fastmcp>` | FastMCP tools | `fastmcp-tool`, `fastmcp-tool-summary` |
-| {doc}`sphinx-autodoc-pytest-fixtures <packages/sphinx-autodoc-pytest-fixtures>` | pytest fixtures (extends `py` domain) | `autofixture`, `autofixtures`, `auto-pytest-plugin` |
-| {doc}`sphinx-autodoc-sphinx <packages/sphinx-autodoc-sphinx>` | Sphinx config | `autoconfigvalue`, `autoconfigvalues` |
+::::{grid} 1 1 2 3
+:gutter: 2
+
+:::{grid-item-card} sphinx-autodoc-api-style
+:link: packages/sphinx-autodoc-api-style
+:link-type: doc
+
+**Subject**: standard Python.
+**Directives**: `autofunction`, `autoclass`, `automodule`.
+:::
+
+:::{grid-item-card} sphinx-autodoc-argparse
+:link: packages/sphinx-autodoc-argparse
+:link-type: doc
+
+**Subject**: argparse parsers — programs, options, subcommands, positionals.
+**Directives**: `argparse` (custom `argparse` domain).
+:::
+
+:::{grid-item-card} sphinx-autodoc-docutils
+:link: packages/sphinx-autodoc-docutils
+:link-type: doc
+
+**Subject**: docutils directives and roles.
+**Directives**: `autodirective`, `autorole`.
+:::
+
+:::{grid-item-card} sphinx-autodoc-fastmcp
+:link: packages/sphinx-autodoc-fastmcp
+:link-type: doc
+
+**Subject**: FastMCP tools, prompts, resources.
+**Directives**: `fastmcp-tool`, `fastmcp-tool-summary`.
+:::
+
+:::{grid-item-card} sphinx-autodoc-pytest-fixtures
+:link: packages/sphinx-autodoc-pytest-fixtures
+:link-type: doc
 
-Each domain package calls `app.setup_extension()` to auto-register its
+**Subject**: pytest fixtures (extends the `py` domain).
+**Directives**: `autofixture`, `autofixtures`, `auto-pytest-plugin`.
+:::
+
+:::{grid-item-card} sphinx-autodoc-sphinx
+:link: packages/sphinx-autodoc-sphinx
+:link-type: doc
+
+**Subject**: Sphinx config values.
+**Directives**: `autoconfigvalue`, `autoconfigvalues`.
+:::
+
+::::
+
+Each autodoc extension calls `app.setup_extension()` to auto-register its
 infrastructure dependencies — downstream projects only need to add the
-domain package to their `extensions` list.
+package to their `extensions` list.
 
 ## Tier 3: Theme and coordinator
 
 | Package | Role |
 |---------|------|
 | {doc}`gp-sphinx <packages/gp-sphinx>` | Coordinator.  `merge_sphinx_config()` wires up the full stack. |
 | {doc}`sphinx-gp-theme <packages/sphinx-gp-theme>` | Furo-based theme with CSS variables and SPA navigation. |
+| {doc}`gp-furo-theme <packages/gp-furo-theme>` | Tailwind v4 port of upstream Furo for git-pull projects. |
 | {doc}`sphinx-fonts <packages/sphinx-fonts>` | IBM Plex via Fontsource — preloaded web fonts. |
 
+## Build tooling
+
+Cross-cutting build utilities that operate outside the docs-build
+runtime — one is a [PEP 517](https://peps.python.org/pep-0517/) build
+backend invoked when wheels are produced; the other is an opt-in
+extension that drives the Vite watcher during `sphinx-autobuild`.
+Both let theme authors keep build artefacts (`static/styles/*.css`,
+`static/scripts/*.js`) out of VCS while still shipping working wheels
+and seamless live-reload during authoring.
+
+::::{grid} 1 1 2 2
+:gutter: 2
+
+:::{grid-item-card} sphinx-vite-builder
+:link: packages/sphinx-vite-builder
+:link-type: doc
+
+[PEP 517](https://peps.python.org/pep-0517/) build backend (or
+hatchling build hook via `[tool.hatch.build.hooks.vite]`) that runs
+`pnpm exec vite build` before delegating wheel/sdist construction to
+hatchling. Also a Sphinx extension that auto-orchestrates
+`vite build --watch` during `sphinx-autobuild` and one-shot
+`vite build` during plain `sphinx-build`.
+Source builds error loudly without pnpm/Node; wheels ship turn-key.
+**Publishable for use outside this workspace** — any vite + Sphinx
+project can adopt either activation path without depending on the
+gp-sphinx coordinator.
+:::
+
+::::
+
 ## How the tiers connect
 
-Every domain package shares the same badge palette, the same componentized
-HTML output structure, and the same type annotation pipeline — so Python
-APIs, pytest fixtures, Sphinx config values, docutils directives, and
-FastMCP tools all look like they belong together.
+Every autodoc extension shares the same badge palette, the same
+componentized HTML output structure, and the same type annotation
+pipeline — so [Python APIs](packages/sphinx-autodoc-api-style.md),
+[pytest fixtures](packages/sphinx-autodoc-pytest-fixtures.md),
+[Sphinx config values](packages/sphinx-autodoc-sphinx.md),
+[docutils directives](packages/sphinx-autodoc-docutils.md), and
+[FastMCP tools](packages/sphinx-autodoc-fastmcp.md) all look like
+they belong together.
 
 This is the **one autodoc design system** principle: a change to the shared
-infrastructure propagates instantly and consistently across all six
-domain packages.
+infrastructure propagates instantly and consistently across every autodoc
+extension in the workspace.

docs/conf.py

@@ -96,11 +96,12 @@
     pytest_fixture_lint_level="none",
     rediraffe_redirects="redirects.txt",
     intersphinx_mapping=intersphinx_mapping,
-    # Enable Vite orchestration: under `sphinx-autobuild`, gp-sphinx-vite
-    # spawns `pnpm exec vite build --watch` so contributors editing
-    # gp-furo-theme/web/src see fresh CSS/JS on disk without remembering
-    # a separate command. No-op for `sphinx-build` (mode resolves to
-    # "prod"), so wheel publishes carry no Node runtime requirement.
+    # Enable Vite orchestration: under `sphinx-autobuild`,
+    # sphinx-vite-builder spawns `pnpm exec vite build --watch` so
+    # contributors editing gp-furo-theme/web/src see fresh CSS/JS on
+    # disk without remembering a separate command. No-op for
+    # `sphinx-build` (mode resolves to "prod"), so wheel publishes
+    # carry no Node runtime requirement.
     vite_orchestration=True,
 )
 globals().update(conf)