diff --git a/docs/README.md b/docs/README.md index 87dc2ad4..47d81f1c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -67,23 +67,27 @@ This builds a local copy of PyRTL's documentation in `docs/_build/html`. ## Screenshots PyRTL is difficult to screenshot consistently, because it typically runs in a -terminal window, and we rarely want to capture the whole window. - -To make our screenshots more consistent, we post-process them with `imagemagick`. -They are first trimmed, to remove any existing inconsistent border, then we add -a consistent 15-pixel black border: +terminal window, and we rarely want to capture the whole window. To make our +screenshots more consistent, we post-process them with `ImageMagick`, automated +with `docs/screenshots/Makefile`: ```shell -$ mogrify -strip -trim -bordercolor black -border 15 screenshot.png +$ make -C docs/screenshots ``` -When importing screenshots into documentation, it's important to set the image -width, because the screenshots typically contain text, and the screenshot's -text should be about the same size as the surrounding text. To compute the -proper `:width:`, take the width of the screenshot's text in characters (`">>> -sim.tracer.render_trace()"` is 29 characters, for example), add two (for the -15-pixel borders), then divide by two. Set width to `:width: {n}em`, where -`{n}` is the computed number (`{n}` is `15` for the example). +When including screenshots into documentation, we must set the image's width +relative to the page's text size, because our screenshots typically contain +text, and the screenshot's text should be about the same size as the page's +surrounding text. We can't assume the surrounding text has a fixed pixel size, +because that depends on factors beyond our control, such as the reader's +display hardware and their browser zoom level. + +To compensate, we manually set each screenshot's `:width:` in reStructuredText. +To compute the proper `:width:`, take the width of the screenshot's text in +characters (`">>> sim.tracer.render_trace()"` is 29 characters, for example), +add two (for the uniform borders added by `ImageMagick`), then divide by two. +Set width to `:width: {n}em`, where `{n}` is the computed number (`{n}` is `15` +for the example). PyRTL's current screenshots were taken in the Ghostty terminal, with 15-point -"JetBrains Mono", using the "Peppermint" theme. +"JetBrains Mono", using the "Peppermint" theme, with ligatures disabled. diff --git a/docs/screenshots/Makefile b/docs/screenshots/Makefile new file mode 100644 index 00000000..bb1caabb --- /dev/null +++ b/docs/screenshots/Makefile @@ -0,0 +1,12 @@ +all: *.png + +# Post-process PyRTL screenshots with ImageMagick: +# * Strip metadata. +# * Trim any existing border. +# * Add a 15-pixel black border. +# +# This process is idempotent. +%.png: .FORCE + mogrify -strip -trim -bordercolor black -border 15 $@ + +.FORCE: