docs-deploy.yml

# .github/workflows/docs-deploy.yml
# GitHub Actions workflow to build and deploy the MkDocs documentation
# site to GitHub Pages with enhanced CI integration and error handling.

name: Deploy Documentation

# Controls when the workflow will run
on:
  push:
    branches:
      - main # Deploy when changes are pushed to the main branch
    paths: # Only run if documentation-related files change
      - "docs/**"
      - "mkdocs.yml"
      - "src/**" # Re-deploy if source code (for mkdocstrings) changes
      - ".github/workflows/docs-deploy.yml" # Re-deploy if this workflow changes
      - "pyproject.toml" # Re-deploy if dependencies change
      - "poetry.lock" # Re-deploy if lock file changes
  workflow_dispatch: # Allows manual triggering
    inputs:
      environment:
        description: 'Deployment environment'
        required: false
        default: 'production'
        type: choice
        options:
          - production
          - staging

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages-${{ github.ref }}"
  cancel-in-progress: false

env:
  PYTHON_VERSION: "3.11"
  POETRY_VERSION: "1.7.1"

jobs:
  # Pre-deployment validation job
  validate:
    name: Pre-deployment Validation
    runs-on: ubuntu-latest
    outputs:
      should-deploy: ${{ steps.validation.outputs.should-deploy }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
          virtualenvs-create: true
          virtualenvs-in-project: true
          installer-parallel: true

      - name: Load cached Poetry virtual environment
        id: cached-poetry-dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-docs-v2-${{ runner.os }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('**/poetry.lock') }}
          restore-keys: |
            venv-docs-v2-${{ runner.os }}-${{ env.PYTHON_VERSION }}-

      - name: Install dependencies
        run: poetry install --no-interaction --with docs

      - name: Verify mkdocs installation
        run: |
          echo "Checking mkdocs installation..."
          poetry run which mkdocs || echo "mkdocs not found in PATH"
          poetry run mkdocs --version || echo "mkdocs --version failed"

      - name: Validate MkDocs configuration
        id: validation
        run: |
          # Test build to validate configuration
          poetry run mkdocs build --clean --strict --verbose

          # Validate all internal links
          echo "✅ MkDocs configuration is valid"
          echo "should-deploy=true" >> $GITHUB_OUTPUT

      - name: Run documentation linting
        run: |
          # Check for broken internal links in markdown files
          echo "Checking documentation quality..."

          # Basic markdown validation could go here
          # You could add markdownlint or other tools

          echo "✅ Documentation validation complete"

  # Main deployment job
  deploy-docs:
    name: Build and Deploy
    needs: validate
    if: needs.validate.outputs.should-deploy == 'true'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history for git info in docs

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
          virtualenvs-create: true
          virtualenvs-in-project: true
          installer-parallel: true

      - name: Load cached Poetry virtual environment
        id: cached-poetry-dependencies-deploy
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-docs-v2-${{ runner.os }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('**/poetry.lock') }}
          restore-keys: |
            venv-docs-v2-${{ runner.os }}-${{ env.PYTHON_VERSION }}-

      - name: Install dependencies
        run: poetry install --no-interaction --with docs

      - name: Build MkDocs site
        run: |
          echo "🏗️ Building MkDocs site..."
          poetry run mkdocs build --clean --strict --verbose

          # Verify build output
          if [ ! -d "site" ]; then
            echo "❌ Build failed: site directory not found"
            exit 1
          fi

          if [ ! -f "site/index.html" ]; then
            echo "❌ Build failed: index.html not found"
            exit 1
          fi

          echo "✅ Build completed successfully"

          # Add CNAME file for custom domain AFTER build
          # echo "docs.codebrief.com" > site/CNAME  # Uncomment and replace with your custom domain if needed

      - name: Optimize build output
        run: |
          echo "🎯 Optimizing build output..."

          # Remove unnecessary files
          find site -name "*.map" -delete
          find site -name ".DS_Store" -delete

          echo "✅ Optimization complete"

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

      - name: Upload GitHub Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

      - name: Report deployment success
        if: success()
        run: |
          echo "🎉 Documentation deployed successfully!"
          echo "📖 Site URL: ${{ steps.deployment.outputs.page_url }}"

  # Post-deployment validation
  post-deploy-check:
    name: Post-deployment Check
    needs: deploy-docs
    runs-on: ubuntu-latest
    if: always() && needs.deploy-docs.result == 'success'

    steps:
      - name: Wait for deployment
        run: sleep 30

      - name: Check site accessibility
        run: |
          SITE_URL="${{ needs.deploy-docs.outputs.page_url || 'https://shorzinator.github.io/CodeBrief' }}"
          echo "🔍 Checking site accessibility at: $SITE_URL"

          # Basic HTTP check
          if curl -f -s -I "$SITE_URL" > /dev/null; then
            echo "✅ Site is accessible"
          else
            echo "⚠️ Site may not be immediately accessible (this is normal for first deployments)"
          fi

      - name: Notify on failure
        if: failure()
        run: |
          echo "❌ Post-deployment check failed"
          echo "This might indicate an issue with the deployment"