From 1691f79621084edfed50a0d97057c4ac5ba8d5c5 Mon Sep 17 00:00:00 2001 From: inference-bot Date: Thu, 12 Nov 2026 03:21:50 +0000 Subject: [PATCH] publishing: complete the pinned toolchain; build.sh self-heals missing plugins MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit requirements.txt pinned only mkdocs-material, so a cold venv lacked mkdocs and mkdocs-redirects — the exact gap that silently stalled the auto-deployer today. build.sh now gates every build on the venv: it verifies the pinned requirements (installing anything missing or off-version — fast local no-op when current) and fails loudly if mkdocs.yml configures a plugin that requirements.txt does not pin. --check-only runs the gates without building, for use as the poller's pre-deploy check. --- publishing/build.sh | 136 +++++++++++++++++++++++++++++++++--- publishing/requirements.txt | 15 +++- 2 files changed, 139 insertions(+), 12 deletions(-) diff --git a/publishing/build.sh b/publishing/build.sh index 1c91831..b30dec0 100755 --- a/publishing/build.sh +++ b/publishing/build.sh @@ -2,16 +2,30 @@ # Build the member-readable documentation site from this repository. # # The repository is the single source of truth. This script: -# 1. stages a mirror of the documents into .site-src/ (generated, gitignored), +# 1. checks the build venv against publishing/requirements.txt and +# self-heals anything missing or off-version (fast local no-op when +# current — no network, a few `pip show` calls); +# 2. checks that every plugin mkdocs.yml configures is pinned in +# requirements.txt (fails loudly naming any that is not); +# 3. stages a mirror of the documents into .site-src/ (generated, gitignored), # because MkDocs cannot read the repository root directly; -# 2. renders .site-src/ to .site-build/ with MkDocs + Material. +# 4. renders .site-src/ to .site-build/ with MkDocs + Material. # # No document is moved, renamed, or rewritten — the staging copy is a build # artifact and disappears with `--clean`. # +# Why the gates: mkdocs-redirects was once missing from the auto-deployer's +# venv and the build failed silently on every poll cycle while the site kept +# serving the previous build. The toolchain gate now installs a missing pin +# automatically, and an un-pinned plugin aborts with a message naming it. +# # Usage: # publishing/build.sh # create/use .venv-docs and build # publishing/build.sh /path/to/venv # use an existing venv +# publishing/build.sh --check-only [venv] +# # gates only, no staging/build (the +# # poller's pre-deploy check; also +# # cold-bootstraps the venv if absent) # # In CI (Woodpecker), install the toolchain and run MkDocs directly: # pip install -r publishing/requirements.txt && mkdocs build --strict @@ -21,10 +35,117 @@ set -euo pipefail REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" cd "$REPO_DIR" +CHECK_ONLY=0 +if [ "${1:-}" = "--check-only" ]; then + CHECK_ONLY=1 + shift +fi VENV="${1:-$REPO_DIR/.venv-docs}" +REQUIREMENTS="$REPO_DIR/publishing/requirements.txt" + +# --- gate 1: pinned toolchain ---------------------------------------------- +# Compare the venv against the pinned requirements; install anything missing +# or off-version. With the venv current this costs a few local `pip show` +# calls and touches no network. +check_toolchain() { + local missing="" req pkg want have + while IFS= read -r req; do + case "$req" in ''|\#*) continue ;; esac + pkg="${req%%[=<>!~]*}" + case "$req" in *==*) want="${req#*==}" ;; *) want="" ;; esac + have="$("$VENV/bin/pip" show "$pkg" 2>/dev/null | sed -n 's/^Version: //p')" + if [ -z "$have" ] || { [ -n "$want" ] && [ "$have" != "$want" ]; }; then + missing="$missing ${pkg}(${want:-any}; have: ${have:-none})" + fi + done < "$REQUIREMENTS" + if [ -n "$missing" ]; then + echo "Self-heal: installing pinned toolchain package(s):$missing" + "$VENV/bin/pip" install -r "$REQUIREMENTS" || { + echo "FATAL: could not install the pinned toolchain into $VENV (network? disk?)" >&2 + exit 1 + } + fi +} + +# --- gate 2: every configured plugin is pinned ------------------------------ +# A plugin configured in mkdocs.yml but absent from requirements.txt builds on +# whichever machine happens to hold it and aborts everywhere else — exactly +# the environment divergence this publishing layer must not allow. Built-ins +# (MkDocs's `search`, the theme plugin `material`) need no package. +check_plugins() { + local names + names="$("$VENV/bin/python" - "$REPO_DIR/mkdocs.yml" <<'PY' +import sys +try: + import yaml +except ImportError: + print("__SKIP__: PyYAML not importable in the build venv") + sys.exit(0) +try: + cfg = yaml.safe_load(open(sys.argv[1])) +except Exception as exc: + print(f"__SKIP__: cannot parse mkdocs.yml ({exc})") + sys.exit(0) +plugins = cfg.get("plugins") or [] +names = [] +if isinstance(plugins, dict): + names = list(plugins) +elif isinstance(plugins, list): + for item in plugins: + if isinstance(item, str): + names.append(item) + elif isinstance(item, dict): + names.extend(item.keys()) +builtins = {"material", "search"} +print("\n".join(n for n in names if n not in builtins)) +PY +)" + if [ -z "$names" ]; then + echo "plugin check OK: only built-in plugins configured" + return 0 + fi + if [ "${names#__SKIP__}" != "$names" ]; then + echo "WARNING: ${names#__SKIP__: }" >&2 + echo "WARNING: plugin cross-check skipped; the mkdocs build itself still fails loudly on a missing plugin" >&2 + return 0 + fi + local pinned="" req plug ok + while IFS= read -r req; do + case "$req" in ''|\#*) continue ;; esac + pinned="$pinned ${req%%[=<>!~]*}" + done < "$REQUIREMENTS" + for plug in $names; do + ok=0 + for cand in "$plug" "mkdocs-$plug"; do + case " $pinned " in *" $cand "*) ok=1 ;; esac + done + if [ "$ok" = 0 ]; then + echo "FATAL: plugin '$plug' is configured in mkdocs.yml but NOT pinned in publishing/requirements.txt." >&2 + echo " Add '==' there (usually mkdocs-$plug) so every build environment" >&2 + echo " installs the same toolchain, then reinstall it in the build venv." >&2 + return 1 + fi + done + echo "plugin check OK: configured plugin(s) $(echo "$names" | tr '\n' ' ') covered by requirements.txt" + return 0 +} + +if [ ! -x "$VENV/bin/python" ]; then + echo "Creating build venv at $VENV" + python3 -m venv "$VENV" + "$VENV/bin/pip" install --quiet --upgrade pip +fi +check_toolchain +check_plugins + +if [ "$CHECK_ONLY" = 1 ]; then + echo "check OK: $VENV satisfies publishing/requirements.txt and every configured plugin" + exit 0 +fi + SITE_SRC="$REPO_DIR/.site-src" -# 1. Stage the documents (Markdown at the root, maintenance/, incidents/) plus +# 3. Stage the documents (Markdown at the root, maintenance/, incidents/) plus # the publishing assets (fonts, CSS, icon). Exclude tooling and build output. rm -rf "$SITE_SRC" mkdir -p "$SITE_SRC" @@ -68,14 +189,7 @@ cp publishing/robots.txt "$SITE_SRC/robots.txt" fi done) -# 2. Build. -if [ ! -x "$VENV/bin/mkdocs" ]; then - echo "Creating build venv at $VENV" - python3 -m venv "$VENV" - "$VENV/bin/pip" install --quiet --upgrade pip - "$VENV/bin/pip" install --quiet -r "$REPO_DIR/publishing/requirements.txt" -fi - +# 4. Build. echo "Building site -> $REPO_DIR/.site-build" "$VENV/bin/mkdocs" build --clean diff --git a/publishing/requirements.txt b/publishing/requirements.txt index a6f09c0..3645642 100644 --- a/publishing/requirements.txt +++ b/publishing/requirements.txt @@ -1,3 +1,16 @@ # Pinned build toolchain for the documentation site. -# Reproducible: `pip install -r publishing/requirements.txt && mkdocs build` +# +# EVERY package the build needs must be pinned here — this is not decoration: +# on 2026-11-12 mkdocs-redirects was missing from the auto-deployer's venv and +# the build failed on every poll cycle with a plugin error while the site kept +# serving the previous build, with nothing telling anyone. build.sh now checks +# this list against the venv before every build and installs anything missing +# (self-heal), and it fails loudly if mkdocs.yml configures a plugin this file +# does not pin. +# +# Reproducible cold build: +# python3 -m venv .venv-docs \ +# && .venv-docs/bin/pip install -r publishing/requirements.txt +mkdocs==1.6.1 mkdocs-material==9.8.0 +mkdocs-redirects==1.2.3