Setup CI/CD Pipeline for GitHub Pages Deployment

[Anselmoo]

Problem

No automated deployment pipeline exists for the VitePress documentation site.

Solution

Create GitHub Actions workflow to build and deploy documentation to GitHub Pages on every push to main.

Implementation

1. GitHub Actions Workflow

Create .github/workflows/docs.yaml:

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'opt/**/*.py'  # Rebuild when docstrings change
      - 'scripts/generate_docs.py'
      - '.github/workflows/docs.yaml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # For git-based features

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: docs/package-lock.json

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Install Python dependencies
        run: uv sync

      - name: Generate API documentation
        run: |
          uv run python scripts/generate_docs.py
          # Verify output
          test -f docs/api/swarm_intelligence.json

      - name: Install Node dependencies
        working-directory: docs
        run: npm ci

      - name: Build VitePress site
        working-directory: docs
        run: npm run build
        env:
          NODE_OPTIONS: '--max_old_space_size=4096'

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

2. VitePress Base Path Configuration

Update docs/.vitepress/config.ts:

export default defineConfig({
  base: '/useful-optimizer/',  // Repository name for GitHub Pages
  // ... rest of config
})

3. Package.json Scripts

Update docs/package.json:

{
  "scripts": {
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview",
    "docs:api": "cd .. && uv run python scripts/generate_docs.py"
  }
}

4. GitHub Pages Settings

Repository Settings → Pages:

• Source: GitHub Actions
• Custom domain: (optional)

5. Dependabot for Docs Dependencies

Add to .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/docs"
    schedule:
      interval: "weekly"
    groups:
      vitepress:
        patterns:
          - "vitepress*"
          - "vue*"
      echarts:
        patterns:
          - "echarts*"
          - "vue-echarts"

6. Build Status Badge

Add to README.md:

[![Documentation](https://github.com/Anselmoo/useful-optimizer/actions/workflows/docs.yaml/badge.svg)](https://anselmoo.github.io/useful-optimizer/)

7. Local Development Script

Create scripts/docs-dev.fish:

#!/usr/bin/env fish
# Regenerate API docs and start dev server

echo "🔄 Generating API documentation..."
uv run python scripts/generate_docs.py

echo "🚀 Starting VitePress dev server..."
cd docs
npm run docs:dev

Deployment Flow

┌─────────────────────────────────────────────────────────────┐
│                      Push to main                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  GitHub Actions Triggered                                    │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ 1. Checkout repository                                  ││
│  │ 2. Setup Node.js + Python + uv                          ││
│  │ 3. Install dependencies                                 ││
│  │ 4. Run scripts/generate_docs.py                         ││
│  │ 5. npm run docs:build                                   ││
│  │ 6. Upload to GitHub Pages artifact                      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Deploy Job                                                  │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ Deploy artifact to GitHub Pages                         ││
│  │ URL: https://anselmoo.github.io/useful-optimizer/       ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Acceptance Criteria

• .github/workflows/docs.yaml created
• Workflow triggers on push to main (docs/ or opt/ changes)
• Python docs generation runs before VitePress build
• VitePress builds successfully in CI
• Site deploys to GitHub Pages
• URL accessible: https://anselmoo.github.io/useful-optimizer/
• Badge added to README
• Dependabot configured for docs dependencies
• Manual workflow dispatch works:

gh workflow run docs.yaml

Complexity

Medium - GitHub Actions + Pages configuration

Dependencies

Depends on: #83 (VitePress setup), #80 (doc generator)
Part of: #52 (Documentation Epic)