fix(docs): Repair documentation deployment workflow and makefile (#37)

ctreffs · web-flow · commit 9b85371a6274 · 2026-02-11T13:32:57.000+01:00
* build(docs): Update Makefile to support versioned documentation paths * docs: Add root redirect for GitHub Pages * conductor(checkpoint): Checkpoint end of Phase 1 * ci: Inject versioned path in documentation build * ci: Verify upload path in documentation workflow * ci: Copy root redirect to documentation output * docs: Remove static redirect file in favor of dynamic generation * ci: Generate root redirect index.html dynamically * ci: Add post-deployment smoke tests * ci: Run documentation check on PRs (no deploy) * ci: Explicitly point root redirect to index.html for DocC compatibility * fix(docs): Ensure output directory exists for documentation generation * Revert "ci: Explicitly point root redirect to index.html for DocC compatibility" This reverts commit f6bb9bb. * ci: Explicitly point root redirect to index.html for DocC compatibility * fix(docs): Ensure output directory exists for documentation generation * fix(ci): Ensure docs output directory exists before generation * fix(ci): Use tabs in Makefile for docs-generate target
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -3,8 +3,14 @@ name: Documentation
 on:
   push:
     branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
@@ -25,7 +31,27 @@ jobs:
           swift-version: "6.1"
 
       - name: Build Documentation
-        run: make docs-generate
+        run: make docs-generate REPO_NAME=math DOCS_VERSION_PATH=main
+
+      - name: Add Root Redirect
+        run: |
+          cat <<EOF > .build/documentation/index.html
+          <!DOCTYPE html>
+          <html>
+          <head>
+              <meta charset="utf-8">
+              <title>Redirecting to Documentation</title>
+              <link rel="canonical" href="main/documentation/fireblademath/index.html">
+              <script>
+                  window.location.href = "main/documentation/fireblademath/index.html" + window.location.hash;
+              </script>
+              <meta http-equiv="refresh" content="0;url=main/documentation/fireblademath/index.html">
+          </head>
+          <body>
+              <p>Redirecting to <a href="main/documentation/fireblademath/index.html">documentation</a>...</p>
+          </body>
+          </html>
+          EOF
 
       - name: Check Documentation Quality
         run: |
@@ -49,3 +75,25 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+
+  smoke-test:
+    name: Post-Deployment Smoke Test
+    needs: deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check Documentation URL
+        run: |
+          # Wait a few seconds for CDN propagation
+          sleep 10
+          # Verify the versioned documentation path exists
+          curl --fail -sL https://fireblade-engine.github.io/math/main/documentation/fireblademath/ | grep -q "FirebladeMath"
+          echo "Documentation is live at /math/main/"
+      
+      - name: Check Root Redirect
+        run: |
+          # Verify that the root URL redirects correctly
+          RESPONSE=$(curl -sI https://fireblade-engine.github.io/math/ | head -n 1)
+          # Note: GitHub Pages might return 200 with the redirect meta tag, or a 301/302 if configured at the DNS level.
+          # Since we use a meta/JS redirect, we check for a 200 OK and then the content.
+          curl -s https://fireblade-engine.github.io/math/ | grep -q "Redirecting to"
+          echo "Root redirect is live at /math/"
diff --git a/Makefile b/Makefile
@@ -2,7 +2,13 @@ UNAME_S := $(shell uname -s)
 SWIFT_FLAGS ?= --disable-sandbox
 PACKAGE_SWIFT_VERSION := $(shell grep "swift-tools-version" Package.swift | head -n 1 | cut -d ":" -f 2 | xargs)
 
-HOSTING_BASE_PATH ?= fireblade-math
+# Repository name on GitHub Pages
+REPO_NAME ?= math
+# Subdirectory for versioned documentation (e.g., main, 1.0.0)
+DOCS_VERSION_PATH ?= main
+
+# The full base path for hosting
+HOSTING_BASE_PATH ?= $(REPO_NAME)/$(DOCS_VERSION_PATH)
 
 # Targets
 .PHONY: setup lint lint-fix test test-coverage clean pre-commit docs docs-preview docs-generate docs-coverage
@@ -19,14 +25,14 @@ docs-preview:
 	swift package --disable-sandbox preview-documentation --target FirebladeMath
 
 docs-generate:
+	mkdir -p .build/documentation/$(DOCS_VERSION_PATH)
 	swift package --disable-sandbox \
 		--allow-writing-to-directory .build/documentation \
 		generate-documentation --target FirebladeMath \
 		--disable-indexing \
 		--transform-for-static-hosting \
 		--hosting-base-path $(HOSTING_BASE_PATH) \
-		--output-path .build/documentation
-
+		--output-path .build/documentation/$(DOCS_VERSION_PATH)
 docs-coverage: docs-check-coverage
 
 docs-check-coverage:
