name: Documentation
on:
push:
branches: [ main ]
paths:
- 'docs/**'
- '.github/workflows/docs.yml'
pull_request:
paths:
- 'docs/**'
workflow_dispatch:
permissions:
contents: write
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build-docs:
name: Build Documentation
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0 # Needed for versioning
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
cache-dependency-path: docs/package-lock.json
- name: Install dependencies
run: |
cd docs
npm ci
- name: Build Docusaurus site
run: |
cd docs
npm run build
- name: Upload build artifact
uses: actions/upload-artifact@v4
with:
name: docusaurus-build
path: docs/build/
retention-days: 7
- name: Generate build summary
run: |
echo "### 📚 Documentation Built Successfully!" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Build location:** \`docs/build/\`" >> $GITHUB_STEP_SUMMARY
echo "**Pages:** $(find docs/build -name "*.html" | wc -l) HTML files" >> $GITHUB_STEP_SUMMARY
deploy-github-pages:
name: Deploy to GitHub Pages
runs-on: ubuntu-latest
needs: build-docs
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Download build artifact
uses: actions/download-artifact@v4
with:
name: docusaurus-build
path: docs/build
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact for Pages
uses: actions/upload-pages-artifact@v3
with:
path: docs/build
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
- name: Deployment summary
run: |
echo "### 🚀 Documentation Deployed!" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**URL:** ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY
echo "**Branch:** ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
echo "**Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
check-links:
name: Check Documentation Links
runs-on: ubuntu-latest
if: github.event_name == 'pull_request'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
cache-dependency-path: docs/package-lock.json
- name: Install dependencies
run: |
cd docs
npm ci
- name: Build documentation
run: |
cd docs
npm run build
- name: Check for broken links
run: |
cd docs
npx broken-link-checker http://localhost:3000 \
--recursive \
--verbose \
--filter-level 3 \
|| echo "⚠️ Some links may be broken. Please review."
continue-on-error: true
validate-openapi:
name: Validate OpenAPI Spec
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
- name: Set up Python
run: uv python install 3.11
- name: Install dependencies
run: uv sync --all-extras
- name: Generate OpenAPI spec
run: |
uv run python -c "
from src.oxide.web.backend.main import app
import json
spec = app.openapi()
with open('openapi.json', 'w') as f:
json.dump(spec, f, indent=2)
"
- name: Validate OpenAPI spec
uses: char0n/swagger-editor-validate@v1
with:
definition-file: openapi.json
- name: Upload OpenAPI spec
uses: actions/upload-artifact@v4
with:
name: openapi-spec
path: openapi.json
retention-days: 30
- name: Validation summary
run: |
echo "### ✅ OpenAPI Spec Validated!" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Spec version:** $(jq -r '.info.version' openapi.json)" >> $GITHUB_STEP_SUMMARY
echo "**Endpoints:** $(jq '.paths | length' openapi.json)" >> $GITHUB_STEP_SUMMARY
