Skip to content

docs: a local preview that stays browsable while the docs are rebuilt - #459

Merged
ocots merged 1 commit into
mainfrom
docs/preview-script
Nov 19, 2026
Merged

ocots merged 1 commit into
mainfrom
docs/preview-script

Conversation

@ocots

@ocots ocots commented Nov 19, 2026

Copy link
Copy Markdown
Member

Refs #449 (T7, known lead). Applied conventions: ct-conventions v0.14.0, ct-agents v0.5.0.

docs/make.jl clears docs/build/ before it builds, so a server pointed at it returns 404 for the whole build. This adds docs/preview.sh, taken from OptimalControl:

docs/preview.sh serve          # http://localhost:5175, in its own terminal
docs/preview.sh build [LOG]    # after each change; prints "preview updated"

build runs julia --project=docs docs/make.jl, copies docs/build/1 into docs/build-preview/ and swaps it in at the end. A failed build keeps the previous preview. The port is 5175 (OptimalControl uses 5174), so both previews can run at once.

Changes

  • docs/preview.sh (new, a local tool: CI does not use it).
  • .gitignore: docs/build-preview*/.
  • docs/make.jl header and docs/src/developers.md ("The documentation"): how to use it.

Test plan

  • Locally: docs/preview.sh build on a fresh worktree whose docs environment was not instantiated fails with "build failed, preview kept" and leaves no preview; after Pkg.instantiate, it builds and prints "preview updated", and docs/build-preview/ is git-ignored.
  • CI (docs build unchanged).

🤖 Generated with Claude Code

`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 <noreply@anthropic.com>
@ocots ocots added the ci on main: changes only Before merging: on main, rerun only the jobs the merged files can affect (never on a release PR) label Nov 19, 2026
@ocots
ocots merged commit 1f2c2a0 into main Nov 19, 2026
8 checks passed
@ocots
ocots deleted the docs/preview-script branch November 19, 2026 22:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci on main: changes only Before merging: on main, rerun only the jobs the merged files can affect (never on a release PR)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant