Auto-build vite assets in docs/ justfile

[tony]

Summary

• Add _assets-build private recipe in docs/justfile that runs pnpm exec vite build before any HTML-output sphinx build, with auto-install of node_modules/ if missing.
• Wire every HTML-output builder (html, dirhtml, singlehtml, epub, htmlhelp, qthelp, devhelp) as a dependent of _assets-build. Non-HTML builders skip the dependency.
• Document the same pattern (justfile + Makefile snippets, plus an explanation of the sphinx-autobuild-vs-sphinx-build divergence) on docs/packages/gp-sphinx-vite.md for downstream users wiring up their own docs orchestration.

Closes the gap that took down https://gp-sphinx.git-pull.com/ during the v0.0.1a15 attempt: cold checkouts and just clean runs left furo-tw.css / furo.js absent from the theme's static directory, sphinx-build silently skipped the missing static files (no -W warning), and the deployed HTML referenced 403'd assets.

Why orchestration-layer, not extension-layer

sphinx-autobuild runs gp-sphinx-vite's builder-inited hook, which detects the autobuild via argv0 / SPHINX_AUTOBUILD env and spawns pnpm exec vite build --watch itself — so just start already Just Works (per commit 013884d's auto-pnpm-install). Plain sphinx-build runs in prod mode where the extension is intentionally a no-op (production wheel installs must not require a Node runtime). So the only correct place to plug the gap for just build is the orchestration layer that calls sphinx-build.

Changes

docs/justfile

Adds:

[private]
_assets-build:
    #!/usr/bin/env bash
    set -euo pipefail
    web_root=$(uv run python -c 'import gp_furo_theme; r = gp_furo_theme.get_vite_root(); print(r or "")' 2>/dev/null || true)
    if [ -z "$web_root" ]; then
        echo "[assets] gp_furo_theme.get_vite_root() returned None — assuming wheel install"
        exit 0
    fi
    if ! command -v pnpm >/dev/null 2>&1; then
        echo "[assets] pnpm not on PATH; skipping vite build"
        exit 0
    fi
    if [ ! -d "$web_root/node_modules" ]; then
        (cd "$web_root" && pnpm install --frozen-lockfile)
    fi
    (cd "$web_root" && pnpm exec vite build)

Each HTML-output recipe gains the : _assets-build prerequisite. clean is extended to wipe the vite output directory so the next build is genuinely cold.

docs/packages/gp-sphinx-vite.md

New ## Wiring just build / make build for downstream users section with the canonical recipe in both justfile and Makefile shapes, plus a pointer to gp_furo_theme.get_vite_root() for users on alternate theme parents.

Design decisions

Resolve the vite root via gp_furo_theme.get_vite_root(), not hard-coded path. The helper returns None for wheel installs (no web/ source tree exists, pre-built assets are already in the wheel) and the absolute path for workspace checkouts. The recipe degrades gracefully in both cases.

Skip silently when pnpm isn't on PATH. Some users may not have pnpm installed (e.g. installing gp-sphinx-vite from a wheel and never planning to author theme assets). The recipe skips with a one-line note rather than aborting the parent build — any pre-existing output remains in place.

Mirror gp_sphinx_vite.hooks._ensure_node_modules semantics in shell. Auto-install of node_modules/ on first run — same code path the autobuild flow already takes — so just clean; just html works without a separate pnpm install step.

Verification

Cold start works end-to-end:

$ rm -rf packages/gp-furo-theme/src/gp_furo_theme/theme/gp-furo/static/
$ just build-docs
[assets] running pnpm exec vite build in .../web
... 57.94 kB furo-tw.css, 4.51 kB furo.js
... build succeeded.

$ ls docs/_build/html/_static/styles/furo-tw.css docs/_build/html/_static/scripts/furo.js
   both present

Test plan

• uv run ruff check . --fix --show-fixes — clean
• uv run ruff format . — unchanged
• uv run mypy — clean (197 source files)
• uv run py.test --reruns 0 -vvv — 1317 passed, 159 skipped
• just build-docs from a wiped static dir — produces styled output with both furo-tw.css and furo.js in _build/html/_static/
• Manual verification that downstream-facing snippets in docs/packages/gp-sphinx-vite.md render correctly under just build-docs

Out of scope (follow-up)

The .github/workflows/{docs,tests,release}.yml workflows still call uv run sphinx-build / uv build / smoke runners directly without any pnpm/vite step — same root cause as the live-site outage, but on the CI side. Will land as a separate commit on this PR (and the PR's [DO NOT MERGE] branch trigger lets us validate the deploy actually styles correctly before merging to main).

The gp-furo-theme smoke runner in scripts/ci/package_tools.py is also separately broken (registers gp_furo_theme as an extension instead of via html_theme = "gp-furo", tripping the package's non-HTML-builder guard) — not in this PR's scope.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.05%. Comparing base (a3b7009) to head (ed1874e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #26   +/-   ##
=======================================
  Coverage   89.04%   89.05%           
=======================================
  Files         183      183           
  Lines       15138    15150   +12     
=======================================
+ Hits        13480    13492   +12     
  Misses       1658     1658           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.