#!/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 '==' 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"