publish docs on gh-pages

Author: jakoch

.github/workflows/release.yml

@@ -289,3 +289,64 @@ jobs:
       #   uses: github/codeql-action/upload-sarif@v3 # https://github.com/github/codeql-action
       #   with:
       #     sarif_file: 'scout-results.sarif.json'
+
+# ---------------------------------------------------------------------------------------
+
+  publish-docs:
+
+# ---------------------------------------------------------------------------------------
+
+    name: "Publish Docs to gh-pages"
+
+    needs: build
+    runs-on: ubuntu-latest
+
+    # run this job only on main branch or on tags, this avoids running on PRs
+    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')
+
+    steps:
+
+      - name: 🤘 Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          fetch-depth: 1
+
+      - name: 🔽 Download all docs artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: version-info-*
+          merge-multiple: true
+          path: tmp
+
+      - name: 📝 Merge both READMEs into a Github Pages index.md
+        run: |
+          cd tmp
+          echo "# cpp-devbox ${{ github.ref_name }} ($(date '+%Y-%m-%d'))" > index.md
+          echo "" >> index.md
+          echo "## Images" >> index.md
+          echo "" >> index.md
+          for codename in bookworm trixie; do
+            if [ -f README-${codename}-base.md ]; then
+              echo "### Base Image (${codename})" >> index.md
+              grep -A2 '^OS Version:' README-${codename}-base.md >> index.md
+              echo "" >> index.md
+            fi
+            if [ -f README-${codename}-with-vulkansdk.md ]; then
+              echo "### With VulkanSDK (${codename})" >> index.md
+              grep -A2 '^OS Version:' README-${codename}-with-vulkansdk.md >> index.md
+              echo "" >> index.md
+            fi
+          done
+
+      - name: ✔ Commit index.md to gh-pages branch
+        run: |
+          cp tmp/index.md index.md
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git add index.md
+          git commit -m "Publish docs from ${GITHUB_REPOSITORY}@${GITHUB_SHA:0:9}"
+
+      - name: 🚀 Push to gh-pages branch
+        run: |
+          git push origin gh-pages