Files
inference-bot b295b5a5b6 publishing: fix check_toolchain dying silently on a missing package
pip show exits non-zero for an absent package; under set -euo pipefail the
command substitution aborted build.sh before the self-heal could run — the
gate then failed the deploy with no message at all. Tolerate the missing
package (that is the case being healed) and report it.
2026-11-12 03:30:11 +00:00

200 lines
7.5 KiB
Bash
Executable File

#!/usr/bin/env bash
# Build the member-readable documentation site from this repository.
#
# The repository is the single source of truth. This script:
# 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;
# 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
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
# NB: the substitution must not fail the script under `set -euo pipefail`
# when the package is absent — a missing package is exactly the case this
# gate exists to heal, not an error to die on.
have="$({ "$VENV/bin/pip" show "$pkg" 2>/dev/null || true; } | 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 '<package>==<version>' 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"
# 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"
tar cf - \
--exclude='.git' \
--exclude='.site-src' \
--exclude='.site-build' \
--exclude='.venv-docs' \
--exclude='*.sh' \
--exclude='*.py' \
--exclude='publishing/webhook-receiver.py' \
--exclude='publishing/webhook-receiver.service' \
--exclude='mkdocs.yml' \
--exclude='.gitignore' \
--exclude='requirements.txt' \
. | tar xf - -C "$SITE_SRC"
# A file that must sit at the site root (crawler rules), not under publishing/.
cp publishing/robots.txt "$SITE_SRC/robots.txt"
# The documents sometimes link to a directory (`incidents/`) the way Gitea
# renders it. A static site has no directory listing, so generate a small
# index page for any documented subdirectory that lacks one. This is a build
# artifact — the documents themselves are never touched.
(cd "$SITE_SRC" && find . -mindepth 1 -type d ! -path './publishing*' | while read -r dir; do
if compgen -G "$dir"/*.md >/dev/null && [ ! -f "$dir/index.md" ]; then
dir_name="$(basename "$dir")"
title="$(echo "$dir_name" | sed 's/-/ /g' | sed 's/^./\u&/')"
{
echo "# $title"
echo
echo "Landing page for this directory, generated by the publishing layer — the"
echo "documents themselves live untouched in the repository."
echo
for f in "$dir"/*.md; do
[ "$(basename "$f")" = "index.md" ] && continue
heading="$(grep -m1 '^# ' "$f" | sed 's/^# //' || true)"
echo "- [${heading:-$(basename "$f" .md)}]($(basename "$f"))"
done
} > "$dir/index.md"
fi
done)
# 4. Build.
echo "Building site -> $REPO_DIR/.site-build"
"$VENV/bin/mkdocs" build --clean
echo "Done: $REPO_DIR/.site-build"