From 167e51111f0b4f85f24b69b775e2351180902d4c Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Thu, 19 Nov 2026 21:58:47 +0100 Subject: [PATCH] docs: a local preview that stays browsable while the docs are rebuilt `make.jl` clears `docs/build/` first, so a server on it shows nothing during a build. `docs/preview.sh build` builds as usual, then swaps the finished site into `docs/build-preview/`; `docs/preview.sh serve` serves it (port 5175). A failed build keeps the previous preview. Taken from OptimalControl's `docs/preview.sh`. Refs #449 Co-Authored-By: Claude Opus 5.5 --- .gitignore | 2 ++ docs/make.jl | 2 ++ docs/preview.sh | 73 ++++++++++++++++++++++++++++++++++++++++++ docs/src/developers.md | 9 ++++++ 4 files changed, 86 insertions(+) create mode 100755 docs/preview.sh diff --git a/.gitignore b/.gitignore index d1a36a371..809223525 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,8 @@ deps/src/ # Build artifacts for creating documentation generated by the Documenter package docs/build/ +# local preview of the documentation (docs/preview.sh) +docs/build-preview*/ docs/site/ # -------------------- diff --git a/docs/make.jl b/docs/make.jl index c2e2a4480..36c11bae2 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -2,6 +2,8 @@ # To serve it: `npx serve docs/build/1 --listen 5173` # Or, with Julia only: # `julia --project=docs -e 'using LiveServer; LiveServer.serve(dir="docs/build/1", single_page=true)'` +# To keep the site browsable while it is rebuilt (make.jl clears docs/build/ first): +# `docs/preview.sh serve` once, then `docs/preview.sh build` after each change. # Append (not prepend): docs/Manifest.toml must win for shared deps; the repo root is only # needed to find the local package (SITE18). diff --git a/docs/preview.sh b/docs/preview.sh new file mode 100755 index 000000000..240175894 --- /dev/null +++ b/docs/preview.sh @@ -0,0 +1,73 @@ +#!/usr/bin/env bash +# Local preview of the documentation that stays browsable while it is rebuilt. +# +# `docs/make.jl` writes the site into `docs/build/`, and clears that folder first, so a +# server pointed at it returns 404 for the whole build. This script builds as usual, then +# copies the finished site into `docs/build-preview/` and swaps it in at the very end. A +# server pointed at `docs/build-preview/` keeps showing the previous site until then, and +# a failed build leaves it untouched. +# +# Usage, from anywhere: +# +# docs/preview.sh build [LOG] build the docs, then update the preview +# (the output of make.jl goes to LOG, default the terminal) +# docs/preview.sh serve [PORT] serve the preview on http://localhost:PORT (default 5175) +# +# Typical session: run `serve` once in a terminal, then `build` after each change and reload +# the page when it prints "preview updated". +# +# This is a local tool: it does not change `make.jl`, and the build runs with whatever +# `draft` setting and `@meta Draft` markers the sources have. `docs/build-preview*/` is +# git-ignored. + +set -euo pipefail + +DOCS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(dirname "$DOCS_DIR")" +PREVIEW="$DOCS_DIR/build-preview" +SITE="$DOCS_DIR/build/1" # where DocumenterVitepress puts the built site + +usage() { + sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' + exit 1 +} + +build() { + local log="${1:-/dev/stdout}" + cd "$REPO_DIR" + if ! julia --project=docs docs/make.jl >"$log" 2>&1; then + echo "build failed, preview kept (see $log)" >&2 + exit 1 + fi + if [ ! -d "$SITE" ]; then + echo "build succeeded but $SITE is missing, preview kept" >&2 + exit 1 + fi + # Copy first, then swap with two renames: the preview is never missing for more than + # the instant between them. + rm -rf "$PREVIEW.new" "$PREVIEW.old" + cp -R "$SITE" "$PREVIEW.new" + if [ -d "$PREVIEW" ]; then mv "$PREVIEW" "$PREVIEW.old"; fi + mv "$PREVIEW.new" "$PREVIEW" + rm -rf "$PREVIEW.old" + echo "preview updated" +} + +serve() { + local port="${1:-5175}" + if [ ! -d "$PREVIEW" ]; then + if [ -d "$SITE" ]; then + cp -R "$SITE" "$PREVIEW" # start from the last build, if any + else + echo "no preview yet: run '$0 build' first" >&2 + exit 1 + fi + fi + exec npx serve "$PREVIEW" --listen "$port" +} + +case "${1:-}" in + build) build "${2:-}" ;; + serve) serve "${2:-}" ;; + *) usage ;; +esac diff --git a/docs/src/developers.md b/docs/src/developers.md index 115792359..a3bf5b9f4 100644 --- a/docs/src/developers.md +++ b/docs/src/developers.md @@ -42,3 +42,12 @@ nothing for the problem pages: their results come from the crons. To build it lo julia --project=docs docs/make.jl npx serve docs/build/1 --listen 5173 ``` + +`make.jl` clears `docs/build/` before it builds, so a server on it shows nothing until the +build ends. To keep the previous site browsable meanwhile, serve the preview once and rebuild +through it; the preview is replaced only when a build succeeds: + +```bash +docs/preview.sh serve # http://localhost:5175, in its own terminal +docs/preview.sh build # after each change; prints "preview updated" +```