docs: single-source the Zensical build recipe in scripts/docs/build.sh

The three-step build (materialise config, zensical build --strict, generate
llms.txt) was copy-pasted in shared.yml, docs-preview.yml, and
build-docs.sh. Move it into scripts/docs/build.sh and call that everywhere.

docs-preview.yml now picks the toolchain from the checkout: pull_request_target
runs the workflow file from the base branch, so hardcoding the Zensical steps
would break previews for older heads and v1.x-targeted PRs (and previews of
this branch before it merges).

Author: maxisbey

.github/workflows/shared.yml

@@ -170,10 +170,5 @@ jobs:
           enable-cache: true
           version: 0.9.5
 
-      - name: Install dependencies
-        run: uv sync --frozen --all-extras --python 3.10
-
-      # Zensical runs no MkDocs plugins/hooks: generate the API reference and
-      # the concrete config, build strictly, then generate llms.txt.
       - name: Build the docs in strict mode
         run: bash scripts/docs/build.sh

scripts/build-docs.sh

@@ -36,18 +36,17 @@ trap cleanup EXIT
 
 # Build the checked-out worktree into its local `site/`, picking the toolchain
 # from the branch's own files rather than hard-coding it here: a branch that
-# ships the Zensical generators (scripts/docs/build_config.py) builds with
-# Zensical, otherwise it falls back to MkDocs. This keeps the combined build
-# correct regardless of which branch triggered it. Zensical requires site_dir to
-# live within the project root, so both paths build to the local `site/` and let
+# ships the Zensical build recipe (scripts/docs/build.sh) builds with it,
+# otherwise it falls back to MkDocs. This keeps the combined build correct
+# regardless of which branch triggered it. Zensical requires site_dir to live
+# within the project root, so both paths build to the local `site/` and let
 # the caller copy it to its destination.
 build_site() {
-    if [[ -f scripts/docs/build_config.py ]]; then
-        uv run --frozen --no-sync python scripts/docs/build_config.py
-        uv run --frozen --no-sync zensical build -f mkdocs.gen.yml --strict
-        uv run --frozen --no-sync python scripts/docs/llms_txt.py --site-dir site
+    if [[ -f scripts/docs/build.sh ]]; then
+        bash scripts/docs/build.sh
     else
-        uv run --frozen --no-sync mkdocs build --site-dir site
+        uv sync --frozen --group docs
+        NO_MKDOCS_2_WARNING=1 uv run --frozen --no-sync mkdocs build --site-dir site
     fi
 }
 
@@ -62,7 +61,6 @@ build_branch() {
 
     (
         cd "$worktree"
-        uv sync --frozen --group docs
         rm -rf site
         build_site
         mkdir -p "$dest"

scripts/docs/build.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# Build the v2 documentation site for this checkout into `site/`.
+#
+# Zensical runs no MkDocs plugins or hooks, so the build is three steps:
+# materialise the API reference pages and the concrete config, build the
+# site strictly, then generate llms.txt and the per-page markdown
+# renditions. This script is the single owner of that recipe, dependency
+# sync included — CI (shared.yml, docs-preview.yml) and scripts/build-docs.sh
+# all call it. The toolchain detection in docs-preview.yml and build-docs.sh
+# keys on this file's path and expects the site under site/.
+#
+# Usage:
+#   scripts/docs/build.sh
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Snippet includes (`--8<--`) resolve against the working directory, which
+# must therefore be the repo root.
+cd "$SCRIPT_DIR/../.."
+
+uv sync --frozen --group docs
+uv run --frozen --no-sync python scripts/docs/build_config.py
+uv run --frozen --no-sync zensical build -f mkdocs.gen.yml --strict
+uv run --frozen --no-sync python scripts/docs/llms_txt.py --site-dir site