ci: rebuild the example dashboard for the dev docs (#358)

[timdegroot1996]

Fixes #358

Problem

scripts/docs/copy-static.mjs copies the committed example/robot_dashboard.html of whatever version it is building. Released versions should indeed serve the example their own code produced, but /dev/ documents unreleased main, where that file is only refreshed when a release is cut — it was 7 commits stale, so the /dev/ example had none of the section tracks, the modal fixes or the date histogram that the /dev/ docs describe right next to it.

Fix

The dev build now rebuilds the example from its own worktree before the docs are built.

• Every version is built in a temporary git worktree, so regenerating in the repo root would never reach the build: rebuild_example() runs scripts/example.py inside the dev worktree, right before copy-static.mjs copies the example into docs/public.
• scripts/example.py runs the package from source (python -m, cwd first on sys.path), so the example is produced by the very code the docs next to it describe.
• The worktree is removed afterwards, so nothing is written into the checkout and example/ keeps whatever the release committed. Released versions are untouched.

deploy.yml gains a Python and a pip install . step — the rebuild needs the package's dependencies, not the package.

Behaviour when Python is missing

A docs build is not worth a Python install locally, so a missing interpreter (or one without robotframework) keeps the committed example and logs why. In CI the same situation would silently bring the stale example back, so there it fails instead (process.env.CI). --no-example / DOCS_SKIP_EXAMPLE=1 skips the rebuild deliberately, which is handy for quick local iteration.

Verified locally

npm run docs:build:versions -- --only dev --main-ref main
=== dev (main) -> /robotframework-dashboard/dev/
[example] rebuilding example/robot_dashboard.html from this worktree
[copy] example/robot_dashboard.html -> docs/public/example/robot_dashboard.html
[namespace] docs/public/example/robot_dashboard.html: localStorage keys prefixed for dev
build complete in 16.78s.

The built dev/example/robot_dashboard.html contains the date histogram; the committed example/robot_dashboard.html still does not, and the checkout stayed clean. --no-example logs the skip and builds in 4.8 s.

Notes

• dev is never served from the docs build cache, so the rebuild runs on every deploy: about 20 s added to the job.
• No change to the release procedure — scripts/example.py is still run and committed when cutting a release, which is what every /vX.Y.Z/ serves. Noted in the release and dev-workflow skills and in CONTRIBUTING.md.

🤖 Generated with Claude Code