From 682c6923a26bc1bd4bd776ff7407fc13a56bd064 Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 15:45:54 -0700 Subject: [PATCH 01/10] add GitHub Actions workflow to build Antora documentation. --- .github/workflows/antora-build.yml | 69 ++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 .github/workflows/antora-build.yml diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml new file mode 100644 index 0000000..d07978e --- /dev/null +++ b/.github/workflows/antora-build.yml @@ -0,0 +1,69 @@ +# Copyright 2021 The Khronos Group, Inc. +# SPDX-License-Identifier: Apache-2.0 + +# Github workflow file for Antora documentation build + +name: Antora Build + +# Controls when the action will run. +on: + pull_request: + types: [ opened, synchronize, reopened ] + # Triggers the workflow on push or manual dispatch + push: + workflow_dispatch: +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} + cancel-in-progress: true + +jobs: + antora-build: + runs-on: ubuntu-latest + + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can + # access it + - uses: actions/checkout@v3 + + # Set up Node.js environment + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '16' + + # Install Antora CLI and site generator + - name: Install Antora + run: npm i -g @antora/cli@3.1 @antora/site-generator@3.1 + + # Setup Antora directory structure + - name: Setup Antora directory structure + run: | + cd antora + make setup + + # Create a simple Antora playbook + - name: Create Antora playbook + run: | + echo "site: + title: Vulkan Guide + url: https://github.com/KhronosGroup/Vulkan-Guide + start_page: guide::index.adoc + content: + sources: + - url: . + start_path: antora + ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true" > antora-playbook.yml + + # Run Antora build + - name: Build Antora site + run: antora --stacktrace antora-playbook.yml + + # Archive the build artifacts + - name: Archive Antora build + uses: actions/upload-artifact@v3 + with: + name: antora-site + path: build/site From f81d07f4c40625c9a5d4b3d6f88c246a9a51703b Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 15:48:45 -0700 Subject: [PATCH 02/10] update GitHub Actions workflow to use v4 of upload-artifact action. --- .github/workflows/antora-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index d07978e..13e8848 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -63,7 +63,7 @@ jobs: # Archive the build artifacts - name: Archive Antora build - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: antora-site path: build/site From d19739a7595425aeef26768f735aa680a64a8e4b Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 15:53:56 -0700 Subject: [PATCH 03/10] enhance Antora build workflow: add debug output, ensure directories exist, and copy files directly. --- .github/workflows/antora-build.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index 13e8848..bd50b08 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -38,6 +38,29 @@ jobs: # Setup Antora directory structure - name: Setup Antora directory structure run: | + # Debug: Print directory structure + echo "Current directory: $(pwd)" + echo "Contents of current directory:" + ls -la + echo "Contents of chapters directory:" + ls -la chapters + echo "Contents of antora directory:" + ls -la antora + + # Create directories if they don't exist + mkdir -p antora/modules/ROOT/pages + mkdir -p antora/modules/ROOT/pages/extensions + mkdir -p antora/modules/ROOT/images + mkdir -p antora/modules/ROOT/images/extensions + + # Copy files directly instead of using make + cp chapters/[A-Za-z]*.adoc antora/modules/ROOT/pages/ + cp chapters/extensions/[A-Za-z]*.adoc antora/modules/ROOT/pages/extensions/ + cp chapters/images/[A-Za-z]*.png antora/modules/ROOT/images/ + cp images/[A-Za-z]*.png antora/modules/ROOT/images/ + cp chapters/images/extensions/[A-Za-z]*.png antora/modules/ROOT/images/extensions/ + + # Now run make setup which should succeed since files are already copied cd antora make setup From 5d8625dc56838d25ce43be224cbf2082e323075e Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 15:59:16 -0700 Subject: [PATCH 04/10] simplify Antora setup in GitHub Actions workflow by leveraging Makefile. --- .github/workflows/antora-build.yml | 26 +------------------------- 1 file changed, 1 insertion(+), 25 deletions(-) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index bd50b08..1ccdbf7 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -38,31 +38,7 @@ jobs: # Setup Antora directory structure - name: Setup Antora directory structure run: | - # Debug: Print directory structure - echo "Current directory: $(pwd)" - echo "Contents of current directory:" - ls -la - echo "Contents of chapters directory:" - ls -la chapters - echo "Contents of antora directory:" - ls -la antora - - # Create directories if they don't exist - mkdir -p antora/modules/ROOT/pages - mkdir -p antora/modules/ROOT/pages/extensions - mkdir -p antora/modules/ROOT/images - mkdir -p antora/modules/ROOT/images/extensions - - # Copy files directly instead of using make - cp chapters/[A-Za-z]*.adoc antora/modules/ROOT/pages/ - cp chapters/extensions/[A-Za-z]*.adoc antora/modules/ROOT/pages/extensions/ - cp chapters/images/[A-Za-z]*.png antora/modules/ROOT/images/ - cp images/[A-Za-z]*.png antora/modules/ROOT/images/ - cp chapters/images/extensions/[A-Za-z]*.png antora/modules/ROOT/images/extensions/ - - # Now run make setup which should succeed since files are already copied - cd antora - make setup + make -f antora/Makefile setup # Create a simple Antora playbook - name: Create Antora playbook From b40910c2ded9e2133307bf06cb28e54e1163d540 Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 21:40:10 -0700 Subject: [PATCH 05/10] improve Antora build workflow: fail on warnings or errors and ensure issues are logged properly. --- .github/workflows/antora-build.yml | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index 1ccdbf7..cf2afd1 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -58,7 +58,26 @@ jobs: # Run Antora build - name: Build Antora site - run: antora --stacktrace antora-playbook.yml + run: | + # Run Antora and capture output and exit code + OUTPUT=$(antora --stacktrace antora-playbook.yml 2>&1) + EXIT_CODE=$? + + # Print the output + echo "$OUTPUT" + + # Check for errors or warnings in the output + # Look for patterns that indicate warnings or errors in Antora output + if echo "$OUTPUT" | grep -i -E "(WARN|WARNING|ERROR):"; then + echo "::error::Antora build produced errors or warnings. Failing the build." + exit 1 + fi + + # Also fail if the Antora command itself failed + if [ $EXIT_CODE -ne 0 ]; then + echo "::error::Antora build failed with exit code $EXIT_CODE" + exit $EXIT_CODE + fi # Archive the build artifacts - name: Archive Antora build From 92d24efd61de86599903bc1ad2917749ddb1a390 Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 21:43:35 -0700 Subject: [PATCH 06/10] refine Antora build workflow: improve error detection by matching additional error patterns. --- .github/workflows/antora-build.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index cf2afd1..fc5da7a 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -68,7 +68,8 @@ jobs: # Check for errors or warnings in the output # Look for patterns that indicate warnings or errors in Antora output - if echo "$OUTPUT" | grep -i -E "(WARN|WARNING|ERROR):"; then + # Match both "ERROR:" and "ERROR (" patterns (like "ERROR (asciidoctor): ...") + if echo "$OUTPUT" | grep -i -E "(WARN|WARNING|ERROR)( |\:)"; then echo "::error::Antora build produced errors or warnings. Failing the build." exit 1 fi From 12e94cbde7ab6a9b7ce6a2da0a73317dd8fc6373 Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 21:45:20 -0700 Subject: [PATCH 07/10] refine Antora build workflow: use `-q` flag with grep for cleaner error detection. --- .github/workflows/antora-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index fc5da7a..8d6a33f 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -69,7 +69,7 @@ jobs: # Check for errors or warnings in the output # Look for patterns that indicate warnings or errors in Antora output # Match both "ERROR:" and "ERROR (" patterns (like "ERROR (asciidoctor): ...") - if echo "$OUTPUT" | grep -i -E "(WARN|WARNING|ERROR)( |\:)"; then + if echo "$OUTPUT" | grep -q -i -E "(WARN|WARNING|ERROR)( |\:)"; then echo "::error::Antora build produced errors or warnings. Failing the build." exit 1 fi From 68c57138ffc83ab99589f99dd78bef6e281ad06f Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 21:48:32 -0700 Subject: [PATCH 08/10] simplify Antora build workflow: streamline error detection logic for warnings and errors. --- .github/workflows/antora-build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml index 8d6a33f..cccdb28 100644 --- a/.github/workflows/antora-build.yml +++ b/.github/workflows/antora-build.yml @@ -68,8 +68,8 @@ jobs: # Check for errors or warnings in the output # Look for patterns that indicate warnings or errors in Antora output - # Match both "ERROR:" and "ERROR (" patterns (like "ERROR (asciidoctor): ...") - if echo "$OUTPUT" | grep -q -i -E "(WARN|WARNING|ERROR)( |\:)"; then + # Using a simpler approach to check for ERROR or WARN in the output + if [[ "$OUTPUT" == *"ERROR"* || "$OUTPUT" == *"WARN"* || "$OUTPUT" == *"WARNING"* ]]; then echo "::error::Antora build produced errors or warnings. Failing the build." exit 1 fi From 0a2e86d9848067864b1f3604b02e7b8beb974bfb Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 21:50:57 -0700 Subject: [PATCH 09/10] enhance Antora build workflow: add support for copying SVG files to the images directory. --- antora/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/antora/Makefile b/antora/Makefile index b4e3f14..85b9640 100644 --- a/antora/Makefile +++ b/antora/Makefile @@ -23,6 +23,7 @@ setup_spec: $(CP) $(wildcard chapters/extensions/[A-Za-z]*.adoc) $(ROOT)/pages/extensions/ mkdir -p $(ROOT)/images $(CP) $(wildcard chapters/images/[A-Za-z]*.png) $(ROOT)/images/ + $(CP) $(wildcard chapters/images/[A-Za-z]*.svg) $(ROOT)/images/ $(CP) $(wildcard images/[A-Za-z]*.png) $(ROOT)/images/ mkdir -p $(ROOT)/images/extensions $(CP) $(wildcard chapters/images/extensions/[A-Za-z]*.png) $(ROOT)/images/extensions From d2b5e3d618a1aa4ecca41f1c85fbd0c987720a18 Mon Sep 17 00:00:00 2001 From: swinston Date: Mon, 7 Jul 2025 21:53:02 -0700 Subject: [PATCH 10/10] fix typo in shader language comparison table formatting --- chapters/high_level_shader_language_comparison.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/high_level_shader_language_comparison.adoc b/chapters/high_level_shader_language_comparison.adoc index fe79620..d814022 100644 --- a/chapters/high_level_shader_language_comparison.adoc +++ b/chapters/high_level_shader_language_comparison.adoc @@ -776,7 +776,7 @@ ConstantBuffer sbt; [[vk::ext_builtin_input(HitTriangleVertexPositionsKHR)]] ---- | Requires `GL_EXT_ray_tracing_position_fetch` -| shadercallcoherent | n.a. +| shadercallcoherent | n.a. | |==== === Compute