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.
200 lines
7.5 KiB
Bash
Executable File
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"
|