docs-images.py

Regenerates the generated images of the docs site (petstore UI screenshots and terminal-capture SVGs) from case lists, or checks that the images and the pages that reference them agree.

When to use

  • A petstore page or a juneau-terminal display changed and its documentation image must be refreshed.
  • You want to know whether every generated image exists and every image reference in pages/ resolves: use --check (it writes nothing).
  • You are adding a screenshot: add a case to docs-images/ui-cases.json or docs-images/terminal-cases.json, then run this script for just that case.

Usage

python3 scripts/docs-images.py                         # regenerate every image
python3 scripts/docs-images.py --check                 # write nothing; report problems
python3 scripts/docs-images.py --source terminal       # one source only
python3 scripts/docs-images.py --only 'PetstoreThemes*' # matching cases (globs)
python3 scripts/docs-images.py --base-url http://localhost:10000
python3 scripts/docs-images.py --juneau-root ~/git/apache/juneau

Options

OptionArgumentDefaultMeaning
--checknoneoffWrite nothing. Report MISSING, ORPHANED, DANGLING and UNREFERENCED lines and exit 1 if any error was found.
--onlyone or more patternsall casesCase ids or image names (globs, matched against the id, the image path or the image file name). It is an error if nothing matches.
--sourceui, terminalbothRegenerate one source only.
--portnumber10000Port of the petstore to reuse or start. Ignored with --base-url.
--base-urlURLreuse or start oneAn already-running petstore to shoot.
--juneau-rootdirectory$JUNEAU_ROOT, then ../master, then ../juneauJuneau source checkout.
--docs-rootdirectoryparent of scripts/Docs checkout. Hidden from --help; for tests.

What it does

  1. Loads scripts/docs-images/ui-cases.json and terminal-cases.json (load_cases). Each case has an id and an image (path relative to static/, for example topics/PetstoreThemes.Stock.1.png). The file's defaults are merged into each case. Duplicate ids, or two cases writing the same image, are errors.
  2. --check: compares the cases with static/ and pages/ (check) and prints one KIND path: detail line per problem:
    • MISSING: a case whose image does not exist;
    • ORPHANED: an image under static/topics or static/developer-info that no case produces and the unmanaged globs do not exempt;
    • DANGLING: an image reference in pages/ to a file that does not exist;
    • UNREFERENCED: a case whose image no page references (a warning; does not fail the check).
  3. Terminal cases: for each case, starts its command (the placeholders {juneau_terminal} and {fixtures} expand to the Juneau checkout‘s juneau_terminal.py and scripts/docs-images/fixtures) in a detached tmux session of fixed size on a private tmux server. It waits for the case’s waitFor regex to appear and the pane to stop changing, captures it with tmux capture-pane -e -p, applies the mask regex replacements, and renders SVG text. A case with panes renders its panes side by side; a panes entry of the form {"stack": [pane, pane]} is a column of panes stacked top to bottom with a divider row between them (the column is as wide as its widest pane, and the image as tall as its tallest column). Defaults are 100 columns, 30 rows and a 60 second timeout.
  4. UI cases: reuses a petstore already answering on http://localhost:<port>, or starts <juneau-root>/scripts/start-petstore-jetty.py --port <port> with the clock fixed (PETSTORE_FIXED_NOW=seed) and stops it on exit. Installs Playwright and Chromium under <juneau-root>/juneau-petstore/juneau-petstore-core/target/js if missing, then runs the Juneau checkout's petstore-browser.cjs harness over the cases (path, actions, selector, viewport, waitUntil, initScript).
  5. Moves images into static/ only after every case of the run succeeded.

Output and exit codes

Progress lines (-> steps, then static/<image> for each image written) on stdout; errors on stderr as ERROR: .... --check prints its findings and a count line. Images are written under static/.

CodeMeaning
0Generated, nothing to generate, or --check found no errors.
1--check found errors, or a generation step failed (missing tool, case failure, port in use, bad cases file).
130Interrupted; no image was replaced.

Gotchas

  • Terminal cases need tmux on the path; UI cases need node and npm.
  • A petstore not started by this script does not run on the fixed clock, so shots showing the date or time of day may drift; the script warns and skips cases marked freshServerOnly.
  • If the port is occupied by something that is not the petstore, the run stops and names the process; pass --port or --base-url.
  • A failed UI run leaves the old images; nothing is half-replaced.
  • The first run can take several minutes (petstore build, Playwright and Chromium download).

See also

  • docs-images/fixtures/ (inputs played back by terminal cases; not entry points), start-docusaurus.py