Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ctreffs merged 18 commits into from
Feb 11, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
d8aaa0c
build(docs): Update Makefile to support versioned documentation paths
ctreffs Feb 11, 2026
5a78c39
docs: Add root redirect for GitHub Pages
ctreffs Feb 11, 2026
f23043c
conductor(checkpoint): Checkpoint end of Phase 1
ctreffs Feb 11, 2026
d5cbe19
ci: Inject versioned path in documentation build
ctreffs Feb 11, 2026
aaedd2a
ci: Verify upload path in documentation workflow
ctreffs Feb 11, 2026
e84a839
ci: Copy root redirect to documentation output
ctreffs Feb 11, 2026
e153bf5
docs: Remove static redirect file in favor of dynamic generation
ctreffs Feb 11, 2026
fe670cd
ci: Generate root redirect index.html dynamically
ctreffs Feb 11, 2026
ec8ec7a
ci: Add post-deployment smoke tests
ctreffs Feb 11, 2026
aeb0c56
ci: Run documentation check on PRs (no deploy)
ctreffs Feb 11, 2026
f6bb9bb
ci: Explicitly point root redirect to index.html for DocC compatibility
ctreffs Feb 11, 2026
db0f539
fix(docs): Ensure output directory exists for documentation generation
ctreffs Feb 11, 2026
2f1e08d
Revert "ci: Explicitly point root redirect to index.html for DocC com…
ctreffs Feb 11, 2026
0c12761
ci: Explicitly point root redirect to index.html for DocC compatibility
ctreffs Feb 11, 2026
3ab0d4c
fix(docs): Ensure output directory exists for documentation generation
ctreffs Feb 11, 2026
9c18e79
Merge branch 'fix/docs-deployment-repaired' into fix/docs-deployment-…
ctreffs Feb 11, 2026
05b4862
fix(ci): Ensure docs output directory exists before generation
ctreffs Feb 11, 2026
3aee3dd
fix(ci): Use tabs in Makefile for docs-generate target
ctreffs Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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: |
Expand All @@ -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/"
12 changes: 9 additions & 3 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down