Automatic documentation screenshots (with bounding-boxes) via codex

1 point

8 months ago

I'd like to share this great documentation trick with codex. Our product's documentation website has lots of screenshots of the UI, often with highlighted sections. I got codex to automate creating them whenever we added a new feature or they need updating.

Pre-requisites

- codex (maybe claude code, but I haven't tried it) - MCPs: chrome-devtools

- [browserframe.sh](https://gist.github.com/CamDavidsonPilon/f381cfbaf983949fdf4b62c6790a8c3b) installed locally

- ImageMagick 7 installed locally

- codex has read/write access to your documentation site (and ideally web frontend to better discover interactions, but maybe not necessary).

I use a custom prompt in ~/.codex/prompts to generate the following:

```

### Adding screenshots (Always do if there is a web UI component to the request)

1. Open http://localhost:3000 using chrome-devtools__navigate_page to open our local development website.

2. Find the page we need.

3. Take viewport screenshot: chrome-devtools__take_screenshot → scratch/screenshots/inventory.png.

4. If we need to highlight a button, or modal, or dropdown, etc:

  1. Run chrome-devtools__evaluate_script with getBoundingClientRect() on the element; record x, y, width, height.

  2. Query window.devicePixelRatio via chrome-devtools__evaluate_script (retina viewport → 2).
  3. Convert rect to image pixels by multiplying x, y, width, height by the devicePixelRatio; compute bottom-right as (x+widthy+height).

  4. Draw highlight bounding box with ImageMagick e.g.
     ```
     magick scratch/screenshots/input.png -fill none -stroke "#ff41ff" -strokewidth 9 -draw "rectangle 2613,144 2930,217"    scratch/screenshots/input_boxed.png.
     ```
     Add a bit of padding too.

5. Use the cli tool `browserframe` to put a frame around the screenshot. Example: ``` browserframe input.png -o input_framed.png ``` Don't use a title in `browserframe`.

6. Screenshots are committed as PNGs and grouped in sub-folders under `static/img/` (for example `static/img/user-guide/`).

7. When adding new screenshots, place the file in the matching doc-area subfolder and reference it with a relative path such as `/img/user-guide/<filename>.png`

8. Close the browser program completely when finished.

### Request

$ARGUMENTS

```

Then in codex, I run:

```

/prompts:add-documentation-for the screenshots in docs page X are out of date, please update. If we reference a element, button, etc., in the text, please highlight it when appropriate.

```

Example: https://docs.pioreactor.com/user-guide/create-cluster

1. Run chrome-devtools__evaluate_script with getBoundingClientRect() on the element; record x, y, width, height. 2. Query window.devicePixelRatio via chrome-devtools__evaluate_script (retina viewport → 2). 3. Convert rect to image pixels by multiplying x, y, width, height by the devicePixelRatio; compute bottom-right as (x+widthy+height). 4. Draw highlight bounding box with ImageMagick e.g. ``` magick scratch/screenshots/input.png -fill none -stroke "#ff41ff" -strokewidth 9 -draw "rectangle 2613,144 2930,217" scratch/screenshots/input_boxed.png. ``` Add a bit of padding too.