164 lines
6.3 KiB
Markdown
164 lines
6.3 KiB
Markdown
# Documentation screenshots
|
|
|
|
Use [repo-helper](https://github.com/jamesread/repo-common) (`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:
|
|
|
|
```asciidoc
|
|
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:
|
|
|
|
```bash
|
|
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`).
|
|
|
|
```ini
|
|
[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:
|
|
|
|
```bash
|
|
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`):
|
|
|
|
1. Wait for `body[loaded-dashboard]` before clicking actions.
|
|
2. Click action buttons via `[title="Action Title"]` or `.action-button button`.
|
|
3. For argument forms, wait for `body[loaded-argument-form]`.
|
|
4. Use `#argument-popup`, input ids (`#container`), etc.
|
|
|
|
Example skeleton:
|
|
|
|
```python
|
|
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:
|
|
|
|
```makefile
|
|
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
|
|
|
|
1. Create `docs/modules/ROOT/images/<topic>/<name>/` with the files above.
|
|
2. Add `config.yaml` that reproduces the doc example in the UI.
|
|
3. Write `setup_*.py` to reach the desired UI state; test selectors against the Vue UI.
|
|
4. Add sections to `screenshots.ini`; output PNG names match what the `.adoc` will reference.
|
|
5. Update the `.adoc` page: `image::<topic>/<name>/<png>[]`.
|
|
6. Run `make update-screenshots` and commit PNGs plus config/scripts.
|
|
7. 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.
|