scripts/preview_wiki.sh31 of 31 statements covered (100.00%).
coveredmissednever traced by Bash (not counted)A line ending in … continues the statement above it and shares its fate.
| 1 | #!/usr/bin/env bash | |
| 2 | # | |
| 3 | # preview_wiki.sh — build the orientation wiki exactly as CI does, then serve | |
| 4 | # it locally with live reload for editing wiki/ pages. | |
| 5 | # | |
| 6 | # Two phases: | |
| 7 | # 1. `mkdocs build --strict` — the byte-for-byte command the PR gate | |
| 8 | # (lint:mkdocs:strict) and the Pages deploy run, so anything that would | |
| 9 | # fail CI fails here first, before you look at a rendered page. | |
| 10 | # 2. `mkdocs serve` — live-reloading preview; edits to wiki/*.md and | |
| 11 | # mkdocs.yml re-render on save. (The serve phase is intentionally not | |
| 12 | # strict: a mid-edit broken link should show an error in the terminal, | |
| 13 | # not kill your preview loop. Re-run the script — or wait for the | |
| 14 | # strict build in phase 1 of your next run — for the CI verdict.) | |
| 15 | # | |
| 16 | # The published site also carries the three coverage reports, at | |
| 17 | # /python-coverage/, /bash-coverage/ and /nodejs-coverage/, merged in by | |
| 18 | # pages.yml at deploy time from the test jobs' artifacts — they are NOT part | |
| 19 | # of the local MkDocs build, so the nav's "Coverage reports" entries point | |
| 20 | # at the live site and the locally served paths 404. That is expected. | |
| 21 | # | |
| 22 | # Usage: | |
| 23 | # ./scripts/preview_wiki.sh # strict build, then serve on :8000 | |
| 24 | # ./scripts/preview_wiki.sh --build-only # strict build into site/, no server | |
| 25 | # ./scripts/preview_wiki.sh --port 9000 # serve on another port | |
| 26 | # | |
| 27 | # Requirements: the docs toolchain on the CURRENT python — install with | |
| 28 | # pip install -e ".[docs]" | |
| 29 | # (in a clean venv, or use the dev container; see CONTRIBUTING.md | |
| 30 | # "Developing the wiki" for the container port-forward invocation). The | |
| 31 | # script never installs anything itself. | |
| 32 | # | |
| 33 | 8 | set -euo pipefail |
| 34 | ||
| 35 | 32 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" |
| 36 | 24 | REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" |
| 37 | 8 | cd "$REPO_ROOT" |
| 38 | ||
| 39 | 8 | BUILD_ONLY=0 |
| 40 | 8 | PORT=8000 |
| 41 | ||
| 42 | 12 | while [ "$#" -gt 0 ]; do |
| 43 | 9 | case "$1" in |
| 44 | --build-only) | |
| 45 | 2 | BUILD_ONLY=1 |
| 46 | 2 | shift |
| 47 | ;; | |
| 48 | --port) | |
| 49 | 5 | [ "$#" -ge 2 ] || { echo "error: --port needs a value" >&2; exit 2; } |
| 50 | 2 | PORT="$2" |
| 51 | 2 | shift 2 |
| 52 | ;; | |
| 53 | -h | --help) | |
| 54 | 2 | sed -n '2,32p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' |
| 55 | 1 | exit 0 |
| 56 | ;; | |
| 57 | *) | |
| 58 | 1 | echo "error: unknown argument '$1' (try --help)" >&2 |
| 59 | 1 | exit 2 |
| 60 | ;; | |
| 61 | esac | |
| 62 | done | |
| 63 | ||
| 64 | 5 | if ! command -v mkdocs >/dev/null 2>&1; then |
| 65 | 1 | echo "error: mkdocs is not on PATH." >&2 |
| 66 | 1 | echo "Install the docs toolchain into your active environment first:" >&2 |
| 67 | 1 | echo " pip install -e \".[docs]\"" >&2 |
| 68 | 1 | echo "See CONTRIBUTING.md — \"Developing the wiki\"." >&2 |
| 69 | 1 | exit 1 |
| 70 | fi | |
| 71 | ||
| 72 | 4 | echo "==> Strict build (the exact check CI runs)" |
| 73 | 4 | mkdocs build --strict |
| 74 | ||
| 75 | 3 | if [ "$BUILD_ONLY" -eq 1 ]; then |
| 76 | 1 | echo "==> Built site/ — open site/index.html, or serve it for working search:" |
| 77 | 1 | echo " ./scripts/preview_wiki.sh --port ${PORT}" |
| 78 | 1 | exit 0 |
| 79 | fi | |
| 80 | ||
| 81 | 2 | echo "==> Serving with live reload at http://127.0.0.1:${PORT}/ (Ctrl-C to stop)" |
| 82 | 2 | exec mkdocs serve --dev-addr "127.0.0.1:${PORT}" |