diff --git a/AGENTS.md b/AGENTS.md index 070e28d4..4037ac69 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,8 @@ Run `make checks` before committing. `test` runs plain PHP scripts `make` does automatically. `hack/demo/demo.sh` / `make screenshots [demo]` render a demo through a -local Docker MediaWiki and regenerate `docs/screenshots/*.png`. Only run -this when asked to, or when a change affects rendering (`resources/`, -`hack/demo/demos.yaml`) — not for routine changes. +local Docker MediaWiki and regenerate `docs/screenshots-$MW_VERSION/*.png` +(`MW_VERSION` defaults to `1.43`, e.g. `MW_VERSION=1.45 make screenshots` to +test against a different MediaWiki version). Only run this when asked to, +or when a change affects rendering (`resources/`, `hack/demo/demos.yaml`) +— not for routine changes. diff --git a/Makefile b/Makefile index 2821285d..8faa1f19 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ local-mathjax: ## Pin the bundled local MathJax submodule, e.g. `make local-math vendor/autoload.php: composer.json composer install --no-progress -screenshots: ## Screenshot a demo page, e.g. `make screenshots custom01` (no demo = every demo in hack/demo/demos.yaml) +screenshots: ## Screenshot a demo page, e.g. `make screenshots custom01` (no demo = every demo in hack/demo/demos.yaml); `MW_VERSION=1.45 make screenshots` targets a different mediawiki Docker image tag (default 1.43) hack/demo/demo.sh screenshot $(filter-out $@,$(MAKECMDGOALS)) # Swallows the extra word in `make screenshots custom01` so make doesn't diff --git a/docs/screenshots-1.43/screenshot-custom01-diff.png b/docs/screenshots-1.43/screenshot-custom01-diff.png new file mode 100644 index 00000000..2e2026f2 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-custom01-diff.png differ diff --git a/docs/screenshots-1.43/screenshot-custom01-rightclick.png b/docs/screenshots-1.43/screenshot-custom01-rightclick.png new file mode 100644 index 00000000..cd8769c3 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-custom01-rightclick.png differ diff --git a/docs/screenshots-1.43/screenshot-custom01.png b/docs/screenshots-1.43/screenshot-custom01.png new file mode 100644 index 00000000..4eff7466 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-custom01.png differ diff --git a/docs/screenshots-1.43/screenshot-custom02-diff.png b/docs/screenshots-1.43/screenshot-custom02-diff.png new file mode 100644 index 00000000..47c5ae42 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-custom02-diff.png differ diff --git a/docs/screenshots-1.43/screenshot-custom02.png b/docs/screenshots-1.43/screenshot-custom02.png new file mode 100644 index 00000000..79f1ab17 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-custom02.png differ diff --git a/docs/screenshots-1.43/screenshot-default01.png b/docs/screenshots-1.43/screenshot-default01.png new file mode 100644 index 00000000..0232c27b Binary files /dev/null and b/docs/screenshots-1.43/screenshot-default01.png differ diff --git a/docs/screenshots-1.43/screenshot-default02-diff.png b/docs/screenshots-1.43/screenshot-default02-diff.png new file mode 100644 index 00000000..f91983f6 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-default02-diff.png differ diff --git a/docs/screenshots-1.43/screenshot-default02-rightclick.png b/docs/screenshots-1.43/screenshot-default02-rightclick.png new file mode 100644 index 00000000..6bfbdd48 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-default02-rightclick.png differ diff --git a/docs/screenshots-1.43/screenshot-default02.png b/docs/screenshots-1.43/screenshot-default02.png new file mode 100644 index 00000000..497538b3 Binary files /dev/null and b/docs/screenshots-1.43/screenshot-default02.png differ diff --git a/docs/screenshots-1.45/screenshot-custom01-diff.png b/docs/screenshots-1.45/screenshot-custom01-diff.png new file mode 100644 index 00000000..9abb43de Binary files /dev/null and b/docs/screenshots-1.45/screenshot-custom01-diff.png differ diff --git a/docs/screenshots-1.45/screenshot-custom01-rightclick.png b/docs/screenshots-1.45/screenshot-custom01-rightclick.png new file mode 100644 index 00000000..8ad8467a Binary files /dev/null and b/docs/screenshots-1.45/screenshot-custom01-rightclick.png differ diff --git a/docs/screenshots-1.45/screenshot-custom01.png b/docs/screenshots-1.45/screenshot-custom01.png new file mode 100644 index 00000000..a4aac08f Binary files /dev/null and b/docs/screenshots-1.45/screenshot-custom01.png differ diff --git a/docs/screenshots-1.45/screenshot-custom02-diff.png b/docs/screenshots-1.45/screenshot-custom02-diff.png new file mode 100644 index 00000000..f86288fc Binary files /dev/null and b/docs/screenshots-1.45/screenshot-custom02-diff.png differ diff --git a/docs/screenshots-1.45/screenshot-custom02.png b/docs/screenshots-1.45/screenshot-custom02.png new file mode 100644 index 00000000..a3e7f3eb Binary files /dev/null and b/docs/screenshots-1.45/screenshot-custom02.png differ diff --git a/docs/screenshots-1.45/screenshot-default01.png b/docs/screenshots-1.45/screenshot-default01.png new file mode 100644 index 00000000..0451ab06 Binary files /dev/null and b/docs/screenshots-1.45/screenshot-default01.png differ diff --git a/docs/screenshots-1.45/screenshot-default02-diff.png b/docs/screenshots-1.45/screenshot-default02-diff.png new file mode 100644 index 00000000..5d390b05 Binary files /dev/null and b/docs/screenshots-1.45/screenshot-default02-diff.png differ diff --git a/docs/screenshots-1.45/screenshot-default02-rightclick.png b/docs/screenshots-1.45/screenshot-default02-rightclick.png new file mode 100644 index 00000000..54a442de Binary files /dev/null and b/docs/screenshots-1.45/screenshot-default02-rightclick.png differ diff --git a/docs/screenshots-1.45/screenshot-default02.png b/docs/screenshots-1.45/screenshot-default02.png new file mode 100644 index 00000000..fc0828f6 Binary files /dev/null and b/docs/screenshots-1.45/screenshot-default02.png differ diff --git a/docs/screenshots/screenshot-custom01-diff.png b/docs/screenshots/screenshot-custom01-diff.png deleted file mode 100644 index 1bfd34bb..00000000 Binary files a/docs/screenshots/screenshot-custom01-diff.png and /dev/null differ diff --git a/docs/screenshots/screenshot-custom01-rightclick.png b/docs/screenshots/screenshot-custom01-rightclick.png deleted file mode 100644 index 5e0da8b0..00000000 Binary files a/docs/screenshots/screenshot-custom01-rightclick.png and /dev/null differ diff --git a/docs/screenshots/screenshot-custom01.png b/docs/screenshots/screenshot-custom01.png deleted file mode 100644 index e1a27a40..00000000 Binary files a/docs/screenshots/screenshot-custom01.png and /dev/null differ diff --git a/docs/screenshots/screenshot-custom02-diff.png b/docs/screenshots/screenshot-custom02-diff.png deleted file mode 100644 index ed843529..00000000 Binary files a/docs/screenshots/screenshot-custom02-diff.png and /dev/null differ diff --git a/docs/screenshots/screenshot-custom02.png b/docs/screenshots/screenshot-custom02.png deleted file mode 100644 index d6c6d706..00000000 Binary files a/docs/screenshots/screenshot-custom02.png and /dev/null differ diff --git a/docs/screenshots/screenshot-default01.png b/docs/screenshots/screenshot-default01.png deleted file mode 100644 index 62588170..00000000 Binary files a/docs/screenshots/screenshot-default01.png and /dev/null differ diff --git a/docs/screenshots/screenshot-default02-diff.png b/docs/screenshots/screenshot-default02-diff.png deleted file mode 100644 index 21e9e4bb..00000000 Binary files a/docs/screenshots/screenshot-default02-diff.png and /dev/null differ diff --git a/docs/screenshots/screenshot-default02-rightclick.png b/docs/screenshots/screenshot-default02-rightclick.png deleted file mode 100644 index 16a6ab7a..00000000 Binary files a/docs/screenshots/screenshot-default02-rightclick.png and /dev/null differ diff --git a/docs/screenshots/screenshot-default02.png b/docs/screenshots/screenshot-default02.png deleted file mode 100644 index 150e6e72..00000000 Binary files a/docs/screenshots/screenshot-default02.png and /dev/null differ diff --git a/hack/demo/demo.sh b/hack/demo/demo.sh index f2e59fb8..2599e678 100755 --- a/hack/demo/demo.sh +++ b/hack/demo/demo.sh @@ -5,21 +5,26 @@ # # Usage: hack/demo/demo.sh [up|down] [demo] # hack/demo/demo.sh screenshot [demo] +# MW_VERSION=1.45 hack/demo/demo.sh screenshot [demo] # `demo` is a top-level key in hack/demo/demos.yaml (e.g. default01, custom01); -# its capture is saved to docs/screenshots/screenshot-.png. Defaults -# to `default01`; `screenshot` with no `demo` given screenshots every demo in -# demos.yaml. +# its capture is saved to docs/screenshots-$MW_VERSION/screenshot-.png. +# Defaults to `default01`; `screenshot` with no `demo` given screenshots +# every demo in demos.yaml. MW_VERSION selects the `mediawiki` Docker image +# tag to test against (default 1.43) — e.g. to check whether a bug is +# specific to one MediaWiki version. set -euo pipefail DEMO_DIR="$(cd "$(dirname "$0")" && pwd)" cd "$DEMO_DIR/../.." -IMAGE=mediawiki:1.43 +MW_VERSION="${MW_VERSION:-1.43}" +IMAGE="mediawiki:$MW_VERSION" NAME=demo PORT=8080 DATA="$PWD/hack/demo/temp" DOCKER_USER=33:33 PASS=demo12345678 PAGE_TITLE=SimpleMathJax +SCREENSHOT_DIR="$PWD/docs/screenshots-$MW_VERSION" # Encodes the configured page title for index.php query-string URLs. API # requests below use curl's --data-urlencode instead. @@ -57,7 +62,10 @@ render_examples() { # Logs in as Admin and edits the configured demo page (not "Main Page", which # the installer already fills with its own default content) with a small # demo showing primes inside $...$/$$...$$ surviving wikitext emphasis -# parsing, prefixed with the demo's own `settings:` block (wrapped in +# parsing, prefixed with a MediaWiki {{CURRENTVERSION}}/SimpleMathJax +# version line (so a screenshot alone shows what it was captured against — +# useful once screenshots exist for more than one MediaWiki version, see +# MW_VERSION) and the demo's own `settings:` block (wrapped in # ) for context. Blanks the page first so the demo edit # always has an empty previous revision to diff against — a real # two-column diff, not just a "page creation" summary — regardless of how @@ -83,9 +91,14 @@ seed_demo_page() { --data-urlencode "text=" \ --data-urlencode "token=$csrf_token" --data-urlencode "format=json" "$url" >/dev/null + local smj_version + smj_version=$(php -r 'echo json_decode(file_get_contents($argv[1]), true)["version"];' "$PWD/extension.json") + local page page=$(mktemp) { + echo "SimpleMathJax $smj_version, MediaWiki {{CURRENTVERSION}}" + echo echo '' local_settings_body "$demo" echo '' @@ -156,17 +169,17 @@ down() { # Screenshots one demo's page with a real browser (Puppeteer); see # screenshot.mjs. Forces a fresh install (down, then up) so the demo's own # `settings:` block is guaranteed to be the one in effect, then saves to -# docs/screenshots/screenshot-.png. A demo with `addRightClickShot: true` -# (see render.php) gets one extra screenshot, -# docs/screenshots/screenshot--rightclick.png, after right-clicking its -# first mjx-container — needed to show MathJax's context menu, e.g. for +# $SCREENSHOT_DIR/screenshot-.png (docs/screenshots-$MW_VERSION by +# default). A demo with `addRightClickShot: true` (see render.php) gets one +# extra screenshot, screenshot--rightclick.png, after right-clicking +# its first mjx-container — needed to show MathJax's context menu, e.g. for # $wgSmjEnableMenu, since the normal capture never triggers one. A demo with # `addDiffShot: true` gets a separate extra screenshot, -# docs/screenshots/screenshot--diff.png, of the demo page's diff -# against the blank revision seed_demo_page saves right before its real -# edit — needed to show $wgSmjIgnoreHtmlClass keeping bare-delimiter -# scanning out of diff views, since a diff is a different page/URL entirely, -# not something a click on the normal capture can reveal. +# screenshot--diff.png, of the demo page's diff against the blank +# revision seed_demo_page saves right before its real edit — needed to show +# $wgSmjIgnoreHtmlClass keeping bare-delimiter scanning out of diff views, +# since a diff is a different page/URL entirely, not something a click on +# the normal capture can reveal. screenshot_one() { local demo="$1" down @@ -179,13 +192,13 @@ screenshot_one() { if [ "$(php "$DEMO_DIR/render.php" "$DEMO_DIR/demos.yaml" "$demo" addrightclickshot)" = "true" ]; then right_click=mjx-container fi - mkdir -p "$PWD/docs/screenshots" + mkdir -p "$SCREENSHOT_DIR" ( cd "$DEMO_DIR" && URL="http://localhost:$PORT/index.php?title=$PAGE_TITLE_URL" \ - OUT="$PWD/../../docs/screenshots/screenshot-$demo.png" \ + OUT="$SCREENSHOT_DIR/screenshot-$demo.png" \ RIGHT_CLICK="$right_click" \ - RIGHT_CLICK_OUT="$PWD/../../docs/screenshots/screenshot-$demo-rightclick.png" \ + RIGHT_CLICK_OUT="$SCREENSHOT_DIR/screenshot-$demo-rightclick.png" \ node screenshot.mjs ) if [ "$(php "$DEMO_DIR/render.php" "$DEMO_DIR/demos.yaml" "$demo" adddiffshot)" = "true" ]; then @@ -194,7 +207,7 @@ screenshot_one() { ( cd "$DEMO_DIR" && URL="http://localhost:$PORT/index.php?title=$PAGE_TITLE_URL&diff=prev&oldid=$revid" \ - OUT="$PWD/../../docs/screenshots/screenshot-$demo-diff.png" \ + OUT="$SCREENSHOT_DIR/screenshot-$demo-diff.png" \ node screenshot.mjs ) fi @@ -209,7 +222,8 @@ screenshot() { # Regenerating every demo: clear old captures first so a demo that got # renamed or removed from demos.yaml doesn't leave a stale screenshot # behind under its old name. - rm -f "$PWD/docs/screenshots"/screenshot-*.png + mkdir -p "$SCREENSHOT_DIR" + rm -f "$SCREENSHOT_DIR"/screenshot-*.png local demo for demo in $(sed -n 's/^- name: //p' "$DEMO_DIR/demos.yaml"); do screenshot_one "$demo"