add GitHub Actions workflow to build Antora documentation. (#325)

* add GitHub Actions workflow to build Antora documentation.

* update GitHub Actions workflow to use v4 of upload-artifact action.

* enhance Antora build workflow: add debug output, ensure directories exist, and copy files directly.

* simplify Antora setup in GitHub Actions workflow by leveraging Makefile.

* improve Antora build workflow: fail on warnings or errors and ensure issues are logged properly.

* refine Antora build workflow: improve error detection by matching additional error patterns.

* refine Antora build workflow: use `-q` flag with grep for cleaner error detection.

* simplify Antora build workflow: streamline error detection logic for warnings and errors.

* enhance Antora build workflow: add support for copying SVG files to the images directory.

* fix typo in shader language comparison table formatting

Author: gpx1000

.github/workflows/antora-build.yml

@@ -0,0 +1,88 @@
+# 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/[email protected] @antora/[email protected]
+
+      # Setup Antora directory structure
+      - name: Setup Antora directory structure
+        run: |
+          make -f antora/Makefile 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: |
+          # 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
+          # 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
+
+          # 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
+        uses: actions/upload-artifact@v4
+        with:
+          name: antora-site
+          path: build/site

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

chapters/high_level_shader_language_comparison.adoc

@@ -776,7 +776,7 @@ ConstantBuffer<SBT> sbt;
 [[vk::ext_builtin_input(HitTriangleVertexPositionsKHR)]]
 ----
   | Requires `GL_EXT_ray_tracing_position_fetch`
-| shadercallcoherent | n.a.
+| shadercallcoherent | n.a. |
 |====
 
 === Compute