Generate cover metadata during developer guide build

Author: shai-almog

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

@@ -21,23 +21,59 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v4
 
-      - name: Update publication metadata for release
-        if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
-        env:
-          RELEASE_TAG: ${{ github.event.release.tag_name }}
+      - name: Determine publication metadata
         run: |
           set -euo pipefail
           REV_DATE="$(date -u +%Y-%m-%d)"
-          VERSION="${RELEASE_TAG:-}"
+          VERSION="${GITHUB_HEAD_REF:-}"
           if [ -z "$VERSION" ] && [ -n "${GITHUB_REF_NAME:-}" ]; then
             VERSION="$GITHUB_REF_NAME"
           fi
+          if [ -z "$VERSION" ] && [ -n "${GITHUB_SHA:-}" ]; then
+            VERSION="${GITHUB_SHA:0:7}"
+          fi
           VERSION="${VERSION#v}"
           if [ -z "$VERSION" ]; then
             VERSION="UNKNOWN"
           fi
-          sed -i -E "s/^:revdate: .*/:revdate: ${REV_DATE}/" docs/developer-guide/developer-guide.asciidoc
-          sed -i -E "s/^:revnumber: .*/:revnumber: ${VERSION}/" docs/developer-guide/developer-guide.asciidoc
+          if date -u -d "$REV_DATE" '+%B %-d, %Y' >/tmp/rev_human 2>/dev/null; then
+            REV_HUMAN_DATE="$(cat /tmp/rev_human)"
+          else
+            REV_HUMAN_DATE="$(date -u '+%B %-d, %Y')"
+          fi
+          {
+            echo "REV_DATE=$REV_DATE"
+            echo "REV_NUMBER=$VERSION"
+            echo "REV_HUMAN_DATE=$REV_HUMAN_DATE"
+          } >> "$GITHUB_ENV"
+
+      - name: Render publication cover artwork
+        run: |
+          set -euo pipefail
+          SOURCE="docs/developer-guide/book-cover.svg"
+          GENERATED="docs/developer-guide/book-cover.generated.svg"
+          cp "$SOURCE" "$GENERATED"
+          export GENERATED
+          python - <<'PY'
+import os
+import re
+from pathlib import Path
+
+target = Path(os.environ["GENERATED"])
+rev = os.environ.get("REV_NUMBER", "UNKNOWN")
+date = os.environ.get("REV_HUMAN_DATE", os.environ.get("REV_DATE", ""))
+replacement = f"Version {rev} - {date}".strip()
+text = target.read_text(encoding="utf-8")
+pattern = re.compile(r"Version\s+[^<]+")
+if not pattern.search(text):
+    raise SystemExit("Could not find version text placeholder in cover artwork")
+text = pattern.sub(replacement, text, count=1)
+target.write_text(text, encoding="utf-8")
+PY
+          {
+            echo "COVER_SVG_ATTR=$(basename "$GENERATED")"
+            echo "GENERATED_COVER_PATH=$GENERATED"
+          } >> "$GITHUB_ENV"
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -55,19 +91,44 @@ jobs:
           HTML_BUILD_DIR="${OUTPUT_ROOT}/html"
           PDF_BUILD_DIR="${OUTPUT_ROOT}/pdf"
           PACKAGE_DIR="${OUTPUT_ROOT}/html-package"
+          COVER_SVG_ATTR_VALUE="${COVER_SVG_ATTR:-book-cover.svg}"
+          GENERATED_COVER_PATH="${GENERATED_COVER_PATH:-}"
           mkdir -p "$HTML_BUILD_DIR" "$PDF_BUILD_DIR"
-          asciidoctor -D "$HTML_BUILD_DIR" -o developer-guide.html docs/developer-guide/developer-guide.asciidoc
-          asciidoctor-pdf -D "$PDF_BUILD_DIR" -o developer-guide.pdf docs/developer-guide/developer-guide.asciidoc
+          asciidoctor \
+            -a revdate="$REV_DATE" \
+            -a revnumber="$REV_NUMBER" \
+            -a cover-svg="$COVER_SVG_ATTR_VALUE" \
+            -D "$HTML_BUILD_DIR" \
+            -o developer-guide.html \
+            docs/developer-guide/developer-guide.asciidoc
+          asciidoctor-pdf \
+            -a revdate="$REV_DATE" \
+            -a revnumber="$REV_NUMBER" \
+            -a cover-svg="$COVER_SVG_ATTR_VALUE" \
+            -D "$PDF_BUILD_DIR" \
+            -o developer-guide.pdf \
+            docs/developer-guide/developer-guide.asciidoc
           rm -rf "$PACKAGE_DIR"
           mkdir -p "$PACKAGE_DIR"
+          if [ -n "$GENERATED_COVER_PATH" ] && [ -f "$GENERATED_COVER_PATH" ]; then
+            cp "$GENERATED_COVER_PATH" "$HTML_BUILD_DIR/$(basename "$GENERATED_COVER_PATH")"
+          fi
           cp "$HTML_BUILD_DIR/developer-guide.html" "$PACKAGE_DIR/"
           for asset_dir in docs/developer-guide/*; do
             base_name="$(basename "$asset_dir")"
             if [ -d "$asset_dir" ] && [ "$base_name" != "sketch" ]; then
               cp -R "$asset_dir" "$PACKAGE_DIR/"
             fi
           done
+          if [ -n "$GENERATED_COVER_PATH" ] && [ -f "$GENERATED_COVER_PATH" ]; then
+            cp "$GENERATED_COVER_PATH" "$PACKAGE_DIR/$(basename "$GENERATED_COVER_PATH")"
+          elif [ -f docs/developer-guide/book-cover.svg ]; then
+            cp docs/developer-guide/book-cover.svg "$PACKAGE_DIR/"
+          fi
           (cd "$PACKAGE_DIR" && zip -r "../developer-guide-html.zip" .)
+          if [ -n "$GENERATED_COVER_PATH" ] && [ -f "$GENERATED_COVER_PATH" ]; then
+            rm -f "$GENERATED_COVER_PATH"
+          fi
 
       - name: Upload HTML artifact
         uses: actions/upload-artifact@v4

docs/developer-guide/.gitignore

@@ -0,0 +1 @@
+book-cover.generated.svg

docs/developer-guide/developer-guide.asciidoc

@@ -16,7 +16,8 @@
 :autofit-option:
 //:hide-uri-scheme:
 :uuid: 92CA37B2-EB2B-4B8F-AC7C-1ED13683F7FB
-:front-cover-image: image:img/cover.png[Front Cover,1000,1600]
+:cover-svg: book-cover.svg
+:front-cover-image: image:{cover-svg}[Front Cover,1000,1600]
 :lang: en-US
 :revdate: 2025-10-20
 :revnumber: DEV-SNAPSHOT