publishing: complete the pinned toolchain; build.sh self-heals missing plugins
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.
This commit is contained in:
1 parent
027cf596ef
commit
1691f79621
2 files changed
+139
-12
No files matched your search
+125
-11
@@ -2,16 +2,30 @@
|
|||||||
# Build the member-readable documentation site from this repository.
|
# Build the member-readable documentation site from this repository.
|
||||||
#
|
#
|
||||||
# The repository is the single source of truth. This script:
|
# 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;
|
# 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
|
# No document is moved, renamed, or rewritten — the staging copy is a build
|
||||||
# artifact and disappears with `--clean`.
|
# 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:
|
# Usage:
|
||||||
# publishing/build.sh # create/use .venv-docs and build
|
# publishing/build.sh # create/use .venv-docs and build
|
||||||
# publishing/build.sh /path/to/venv # use an existing venv
|
# 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:
|
# In CI (Woodpecker), install the toolchain and run MkDocs directly:
|
||||||
# pip install -r publishing/requirements.txt && mkdocs build --strict
|
# pip install -r publishing/requirements.txt && mkdocs build --strict
|
||||||
@@ -21,10 +35,117 @@ set -euo pipefail
|
|||||||
REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||||
cd "$REPO_DIR"
|
cd "$REPO_DIR"
|
||||||
|
|
||||||
|
CHECK_ONLY=0
|
||||||
|
if [ "${1:-}" = "--check-only" ]; then
|
||||||
|
CHECK_ONLY=1
|
||||||
|
shift
|
||||||
|
fi
|
||||||
VENV="${1:-$REPO_DIR/.venv-docs}"
|
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 '<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"
|
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.
|
# the publishing assets (fonts, CSS, icon). Exclude tooling and build output.
|
||||||
rm -rf "$SITE_SRC"
|
rm -rf "$SITE_SRC"
|
||||||
mkdir -p "$SITE_SRC"
|
mkdir -p "$SITE_SRC"
|
||||||
@@ -68,14 +189,7 @@ cp publishing/robots.txt "$SITE_SRC/robots.txt"
|
|||||||
fi
|
fi
|
||||||
done)
|
done)
|
||||||
|
|
||||||
# 2. Build.
|
# 4. 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
|
|
||||||
|
|
||||||
echo "Building site -> $REPO_DIR/.site-build"
|
echo "Building site -> $REPO_DIR/.site-build"
|
||||||
"$VENV/bin/mkdocs" build --clean
|
"$VENV/bin/mkdocs" build --clean
|
||||||
|
|
||||||
|
|||||||
@@ -1,3 +1,16 @@
|
|||||||
# Pinned build toolchain for the documentation site.
|
# 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-material==9.8.0
|
||||||
|
mkdocs-redirects==1.2.3
|
||||||
Reference in new issue
Block a user