From d8aaa0c91913bb9e23d4f43ac68f6b60f0a81b78 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:14:27 +0100 Subject: [PATCH 01/17] build(docs): Update Makefile to support versioned documentation paths --- Makefile | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 39d92c1..00201c3 100644 --- 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 @@ -25,7 +31,7 @@ docs-generate: --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 From 5a78c394072865df5b7eee2f741c0d4422e81321 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:14:43 +0100 Subject: [PATCH 02/17] docs: Add root redirect for GitHub Pages --- scripts/docs-redirect.html | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 scripts/docs-redirect.html diff --git a/scripts/docs-redirect.html b/scripts/docs-redirect.html new file mode 100644 index 0000000..a5f8550 --- /dev/null +++ b/scripts/docs-redirect.html @@ -0,0 +1,15 @@ + + + + + Redirecting to Documentation + + + + + +

Redirecting to documentation...

+ + From f23043cbaeb32a9ae467bfe15e35971269fc32e6 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:16:59 +0100 Subject: [PATCH 03/17] conductor(checkpoint): Checkpoint end of Phase 1 From d5cbe196df7d5c724144513e95d1171691433793 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:17:07 +0100 Subject: [PATCH 04/17] ci: Inject versioned path in documentation build --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5cbdc26..0704eff 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -25,7 +25,7 @@ jobs: swift-version: "6.1" - name: Build Documentation - run: make docs-generate + run: make docs-generate REPO_NAME=math DOCS_VERSION_PATH=main - name: Check Documentation Quality run: | From aaedd2a0a90eb3d73deac30a66023970cddf05ba Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:17:21 +0100 Subject: [PATCH 05/17] ci: Verify upload path in documentation workflow From e84a83944367676fb6a1139771b7f0005e8a6fdc Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:17:30 +0100 Subject: [PATCH 06/17] ci: Copy root redirect to documentation output --- .github/workflows/docs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0704eff..cb40700 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -27,6 +27,9 @@ jobs: - name: Build Documentation run: make docs-generate REPO_NAME=math DOCS_VERSION_PATH=main + - name: Add Root Redirect + run: cp scripts/docs-redirect.html .build/documentation/index.html + - name: Check Documentation Quality run: | make docs-check-coverage From e153bf5db416031013cb35e066e2bc0901c0accc Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:18:47 +0100 Subject: [PATCH 07/17] docs: Remove static redirect file in favor of dynamic generation --- scripts/docs-redirect.html | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 scripts/docs-redirect.html diff --git a/scripts/docs-redirect.html b/scripts/docs-redirect.html deleted file mode 100644 index a5f8550..0000000 --- a/scripts/docs-redirect.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - - Redirecting to Documentation - - - - - -

Redirecting to documentation...

- - From fe670cded1bee42bc5922ef02c5839fb1512ea68 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:18:56 +0100 Subject: [PATCH 08/17] ci: Generate root redirect index.html dynamically --- .github/workflows/docs.yml | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cb40700..a8867e6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -28,7 +28,24 @@ jobs: run: make docs-generate REPO_NAME=math DOCS_VERSION_PATH=main - name: Add Root Redirect - run: cp scripts/docs-redirect.html .build/documentation/index.html + run: | + cat < .build/documentation/index.html + + + + + Redirecting to Documentation + + + + + +

Redirecting to documentation...

+ + + EOF - name: Check Documentation Quality run: | From ec8ec7ae865e5b6cfa6c5a7c29bd6d3b13b2f33e Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:19:47 +0100 Subject: [PATCH 09/17] ci: Add post-deployment smoke tests --- .github/workflows/docs.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a8867e6..0b06b0c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -69,3 +69,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/" From aeb0c5653a758dba0692a1f8d4fcea0db435a6eb Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:24:05 +0100 Subject: [PATCH 10/17] ci: Run documentation check on PRs (no deploy) --- .github/workflows/docs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0b06b0c..ec0520b 100644 --- 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 From f6bb9bb1b2eb18aecdf5eab7f6a4f230b542dad7 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:33:47 +0100 Subject: [PATCH 11/17] ci: Explicitly point root redirect to index.html for DocC compatibility --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ec0520b..4ac1208 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,14 +41,14 @@ jobs: Redirecting to Documentation - + - + -

Redirecting to documentation...

+

Redirecting to documentation...

EOF From db0f5393e001f64cf650ef015266ce8a07452f9d Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:45:22 +0100 Subject: [PATCH 12/17] fix(docs): Ensure output directory exists for documentation generation --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 00201c3..101feb4 100644 --- a/Makefile +++ b/Makefile @@ -31,7 +31,7 @@ docs-generate: --disable-indexing \ --transform-for-static-hosting \ --hosting-base-path $(HOSTING_BASE_PATH) \ - --output-path .build/documentation/$(DOCS_VERSION_PATH) + --output-path .build/documentation/$(DOCS_VERSION_PATH) && mkdir -p .build/documentation/$(DOCS_VERSION_PATH) docs-coverage: docs-check-coverage From 2f1e08d09cd282e38988db5e1bb8ed502b665d29 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:46:20 +0100 Subject: [PATCH 13/17] Revert "ci: Explicitly point root redirect to index.html for DocC compatibility" This reverts commit f6bb9bb1b2eb18aecdf5eab7f6a4f230b542dad7. --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4ac1208..ec0520b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,14 +41,14 @@ jobs: Redirecting to Documentation - + - + -

Redirecting to documentation...

+

Redirecting to documentation...

EOF From 0c12761c51592d7e5a0c3b7b280c0cd9e17de29c Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:33:47 +0100 Subject: [PATCH 14/17] ci: Explicitly point root redirect to index.html for DocC compatibility --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ec0520b..4ac1208 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,14 +41,14 @@ jobs: Redirecting to Documentation - + - + -

Redirecting to documentation...

+

Redirecting to documentation...

EOF From 3ab0d4c24bd1578488211939dab4e56fed6790a3 Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 11:45:22 +0100 Subject: [PATCH 15/17] fix(docs): Ensure output directory exists for documentation generation --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 00201c3..101feb4 100644 --- a/Makefile +++ b/Makefile @@ -31,7 +31,7 @@ docs-generate: --disable-indexing \ --transform-for-static-hosting \ --hosting-base-path $(HOSTING_BASE_PATH) \ - --output-path .build/documentation/$(DOCS_VERSION_PATH) + --output-path .build/documentation/$(DOCS_VERSION_PATH) && mkdir -p .build/documentation/$(DOCS_VERSION_PATH) docs-coverage: docs-check-coverage From 05b48629d92530ce22e7372e98dda89d6d22df6f Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 13:11:25 +0100 Subject: [PATCH 16/17] fix(ci): Ensure docs output directory exists before generation --- Makefile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index 101feb4..4675b4c 100644 --- a/Makefile +++ b/Makefile @@ -25,14 +25,14 @@ docs-preview: swift package --disable-sandbox preview-documentation --target FirebladeMath docs-generate: - 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/$(DOCS_VERSION_PATH) && mkdir -p .build/documentation/$(DOCS_VERSION_PATH) - + 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/$(DOCS_VERSION_PATH) docs-coverage: docs-check-coverage docs-check-coverage: From 3aee3ddfca817e053505fe98689a03c5efbcee9c Mon Sep 17 00:00:00 2001 From: Christian Treffs Date: Wed, 11 Feb 2026 13:18:33 +0100 Subject: [PATCH 17/17] fix(ci): Use tabs in Makefile for docs-generate target --- Makefile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index 4675b4c..336a7fe 100644 --- a/Makefile +++ b/Makefile @@ -25,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/$(DOCS_VERSION_PATH) + 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/$(DOCS_VERSION_PATH) docs-coverage: docs-check-coverage docs-check-coverage: