diff --git a/.github/workflows/developer-guide-docs.yml b/.github/workflows/developer-guide-docs.yml index ee2c36a9db..974795097f 100644 --- a/.github/workflows/developer-guide-docs.yml +++ b/.github/workflows/developer-guide-docs.yml @@ -2,6 +2,7 @@ name: Build Developer Guide Docs on: pull_request: + types: [opened, synchronize, reopened, ready_for_review] paths: - 'docs/developer-guide/**' - '.github/workflows/developer-guide-docs.yml' @@ -21,23 +22,44 @@ 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 + python3 -c "import os, re, pathlib; target = pathlib.Path(os.environ['GENERATED']); 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); assert count == 1, 'Could not find version text placeholder in cover artwork'; target.write_text(new_text, encoding='utf-8')" + { + echo "COVER_SVG_ATTR=$(basename "$GENERATED")" + echo "GENERATED_COVER_PATH=$GENERATED" + } >> "$GITHUB_ENV" - name: Set up Ruby uses: ruby/setup-ruby@v1 @@ -55,11 +77,28 @@ 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")" @@ -67,7 +106,15 @@ jobs: 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 diff --git a/docs/developer-guide/.gitignore b/docs/developer-guide/.gitignore new file mode 100644 index 0000000000..7463ec2ce5 --- /dev/null +++ b/docs/developer-guide/.gitignore @@ -0,0 +1 @@ +book-cover.generated.svg diff --git a/docs/developer-guide/developer-guide.asciidoc b/docs/developer-guide/developer-guide.asciidoc index 66232ad8ef..a996c56b56 100644 --- a/docs/developer-guide/developer-guide.asciidoc +++ b/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