Extract developer guide cover prep into script

Author: shai-almog

.github/workflows/developer-guide-docs.yml

@@ -62,44 +62,11 @@ jobs:
           GENERATED_PNG="docs/developer-guide/book-cover.generated.png"
           cp "$SOURCE" "$GENERATED_SVG"
           export GENERATED_SVG
-          python3 - <<'PY'
-import os
-import pathlib
-import re
-
-target = pathlib.Path(os.environ['GENERATED_SVG'])
-text = target.read_text(encoding='utf-8')
-
-rev = os.environ.get('REV_NUMBER', 'UNKNOWN')
-date = os.environ.get('REV_HUMAN_DATE') or os.environ.get('REV_DATE', '')
-replacement = f"Version {rev}" + (f" - {date}" if date else '')
-
-new_text, count = re.subn(r'Version\s+[^<]+', replacement.strip(), text, count=1)
-if count != 1:
-    raise RuntimeError('Could not find version text placeholder in cover artwork')
-
-variables = {
-    name: value.strip()
-    for name, value in re.findall(r'--([\w-]+):\s*([^;]+);', new_text)
-}
-
-var_counter = {'count': 0}
-
-def replace_var(match):
-    name = match.group(1)
-    value = variables.get(name)
-    if value is None:
-        return match.group(0)
-    var_counter['count'] += 1
-    return value
-
-new_text = re.sub(r'var\(--([\w-]+)\)', replace_var, new_text)
-
-target.write_text(new_text, encoding='utf-8')
-
-print(f"Injected cover legend: {replacement.strip()}")
-print(f"Resolved {var_counter['count']} CSS variable references for rasterization")
-PY
+          python3 scripts/developer-guide/prepare_cover_artwork.py \
+            "$GENERATED_SVG" \
+            --rev-number "$REV_NUMBER" \
+            --rev-human-date "$REV_HUMAN_DATE" \
+            --rev-date "$REV_DATE"
           echo "Rasterizing cover artwork to ${GENERATED_PNG}" >&2
           rsvg-convert -w 2551 -h 3579 "$GENERATED_SVG" -o "$GENERATED_PNG"
           ls -l "$GENERATED_PNG"

scripts/developer-guide/prepare_cover_artwork.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Prepare developer guide cover artwork for rasterization."""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import re
+import sys
+
+
+VERSION_PATTERN = re.compile(r"Version\s+[^<]+")
+CSS_VARIABLE_DECL_PATTERN = re.compile(r"--([\w-]+):\s*([^;]+);")
+CSS_VARIABLE_REF_PATTERN = re.compile(r"var\(--([\w-]+)\)")
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("svg_path", help="Path to the SVG file to update")
+    parser.add_argument("--rev-number", required=True, help="Revision number to embed")
+    parser.add_argument("--rev-human-date", default="", help="Human readable revision date")
+    parser.add_argument("--rev-date", default="", help="Fallback machine readable revision date")
+    return parser.parse_args(argv)
+
+
+def inject_version_label(svg_text: str, version_label: str) -> str:
+    updated_text, count = VERSION_PATTERN.subn(version_label, svg_text, count=1)
+    if count != 1:
+        raise RuntimeError("Could not find version text placeholder in cover artwork")
+    return updated_text
+
+
+def resolve_css_variables(svg_text: str) -> tuple[str, int]:
+    variables = {name: value.strip() for name, value in CSS_VARIABLE_DECL_PATTERN.findall(svg_text)}
+    replacement_count = 0
+
+    def replace(match: re.Match[str]) -> str:
+        nonlocal replacement_count
+        name = match.group(1)
+        value = variables.get(name)
+        if value is None:
+            return match.group(0)
+        replacement_count += 1
+        return value
+
+    resolved_text = CSS_VARIABLE_REF_PATTERN.sub(replace, svg_text)
+    return resolved_text, replacement_count
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+
+    svg_path = pathlib.Path(args.svg_path)
+    svg_text = svg_path.read_text(encoding="utf-8")
+
+    revision_date = args.rev_human_date or args.rev_date
+    version_label = f"Version {args.rev_number}".strip()
+    if revision_date:
+        version_label = f"{version_label} - {revision_date.strip()}"
+
+    svg_text = inject_version_label(svg_text, version_label)
+    svg_text, replacement_count = resolve_css_variables(svg_text)
+
+    svg_path.write_text(svg_text, encoding="utf-8")
+
+    print(f"Injected cover legend: {version_label}")
+    print(f"Resolved {replacement_count} CSS variable references for rasterization")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))