6.3 KiB

Raw Permalink Blame History

Documentation screenshots

Use repo-helper (repo-helper screenshot) to keep Antora doc images up to date. Each documented UI feature gets its own folder under docs/modules/ROOT/images/.

Reference implementation: args/suggestions/.

Folder layout

Create one folder per doc page (or logical screenshot group):

docs/modules/ROOT/images/<topic>/<name>/
├── screenshots.ini      # batch capture config for repo-helper
├── config.yaml          # minimal OliveTin config for this screenshot only
├── setup_<variant>.py   # Selenium setup script(s); each defines run(driver)
├── Makefile             # start OliveTin, capture, stop
├── .gitignore           # runtime artifacts (see below)
└── *.png                # output images (committed)

Wire images in the matching .adoc page:

image::<topic>/<name>/my-screenshot.png[]

Paths are relative to docs/modules/ROOT/images/.

Port and OliveTin instance

Doc screenshots use a dedicated port (not 1337) so they do not clash with a dev server.
All screenshot folders share port 11337.
Set the same port in config.yaml (listenAddressSingleHTTPFrontend) and screenshots.ini (base_url).

Start OliveTin from service/ so the webui is found:

cd service && ./OliveTin -configdir /path/to/screenshot/folder/

The Makefile handles start/wait/capture/stop.

screenshots.ini

Each [section] with a url is one PNG. Section name (or section title) becomes the filename (name.png).

[DEFAULT]
base_url = http://localhost:11337/
dir = .
width = 640
height = 480
post_script_sleep = 0.5

[my-screenshot]
url = .
name = my-screenshot
script = setup_my_screenshot.py

Notes:

--config must point at the real screenshots.ini in the folder; relative paths (script, dir) resolve from the INI directory.
url = . loads the dashboard at base_url.
Override width, height, script, etc. per section when needed.

Capture:

cd docs/modules/ROOT/images/<topic>/<name>
make update-screenshots
# or, if OliveTin is already running on that port:
repo-helper screenshot --config screenshots.ini

config.yaml

Keep configs minimal: only actions, dashboards, and settings required for the screenshot.

Match YAML examples shown in the doc page.
Disable noise: checkForUpdates: false, showFooter: false, logLevel: "WARN".
Set argument type explicitly to avoid startup warnings.
Omit icon on actions unless the screenshot needs a specific glyph. OliveTin 3k applies a default action icon (defaultIconForActions, currently the neutral CLI glyph) when icon is not set.

Reuse integration-test patterns where possible (integration-tests/tests/*/config.yaml).

Setup scripts (Python)

repo-helper loads each --script file and calls run(driver). Scripts run in isolation (no imports from sibling modules unless you add sys.path yourself); prefer one self-contained file per variant.

UI setup should mirror integration tests (integration-tests/lib/elements.js):

Wait for body[loaded-dashboard] before clicking actions.
Click action buttons via [title="Action Title"] or .action-button button.
For argument forms, wait for body[loaded-argument-form].
Use #argument-popup, input ids (#container), etc.

Example skeleton:

import time
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait

def run(driver):
    WebDriverWait(driver, 15).until(
        lambda d: d.find_element(By.TAG_NAME, "body").get_attribute("loaded-dashboard")
    )
    driver.find_element(By.CSS_SELECTOR, '[title="My Action"]').click()
    WebDriverWait(driver, 15).until(
        lambda d: d.find_element(By.TAG_NAME, "body").get_attribute("loaded-argument-form")
    )
    # optional: frame the form, open menus, inject overlays — see args/suggestions/
    time.sleep(0.2)

Headless Chrome limitations

repo-helper uses headless Chrome only. Native browser UI (e.g. <datalist> dropdowns, date pickers) often does not appear in screenshots. When needed, use driver.execute_script(...) in the setup script to render a representative overlay after opening the real form. See args/suggestions/setup_chrome.py and setup_firefox.py.

Makefile template

Each screenshot folder needs only a thin Makefile that sets CONFIGDIR and includes the shared rules:

CONFIGDIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
include ../../screenshots.mk

Shared targets (defined in docs/modules/ROOT/images/screenshots.mk):

make start — background OliveTin with this folder's config.yaml
make or make update-screenshots — stop any instance on 11337, start, run repo-helper screenshot --config screenshots.ini, stop
make stop — kill whatever is listening on port 11337

.gitignore (per folder)

custom-webui/
__pycache__/

Checklist for a new doc screenshot

Create docs/modules/ROOT/images/<topic>/<name>/ with the files above.
Add config.yaml that reproduces the doc example in the UI.
Write setup_*.py to reach the desired UI state; test selectors against the Vue UI.
Add sections to screenshots.ini; output PNG names match what the .adoc will reference.
Update the .adoc page: image::<topic>/<name>/<png>[].
Run make update-screenshots and commit PNGs plus config/scripts.
Remove obsolete PNGs from images/ if paths moved.

Prompt template (for agents)

Use or adapt this when asking to add or refresh doc screenshots:

Update the documentation screenshot(s) for <page.adoc>.

Put everything in docs/modules/ROOT/images/<topic>/<name>/: screenshots.ini, config.yaml, setup script(s), Makefile, .gitignore, and output PNGs.

Follow docs/modules/ROOT/images/SCREENSHOTS.md and copy structure from docs/modules/ROOT/images/args/suggestions/.

Use a dedicated OliveTin port (not 1337); start from service/ with -configdir pointing at the screenshot folder.

Setup scripts should wait for loaded-dashboard / loaded-argument-form like integration tests; reuse selectors from integration-tests/lib/elements.js where applicable.

Update image:: paths in the .adoc page to match the new folder.

Run make update-screenshots and verify the PNGs before finishing.

6.3 KiB Raw Permalink Blame History