docs.yml

name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  build-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Free up disk space
      run: |
        echo "Disk space before cleanup:"
        df -h
        sudo rm -rf /usr/share/dotnet
        sudo rm -rf /usr/local/lib/android
        sudo rm -rf /opt/ghc
        sudo rm -rf /opt/hostedtoolcache/CodeQL
        sudo docker image prune --all --force
        echo "Disk space after cleanup:"
        df -h
      
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'
    
    - name: Install system dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y \
          libgl1 \
          libglib2.0-0 \
          libgomp1 \
          libsm6 \
          libxrender1 \
          libxext6 \
          libxrandr2 \
          libxi6
        sudo apt-get clean
        sudo rm -rf /var/lib/apt/lists/*
        
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip uv
        uv pip install --system -e ".[docs]"

    - name: Clear pip cache
      run: |
        pip cache purge || true
        
    - name: Build documentation
      run: |
        cd docs
        make html
        
    - name: Check for warnings
      run: |
        cd docs
        make html SPHINXOPTS="--keep-going"
      continue-on-error: true
    
    - name: Disable Jekyll processing
      run: touch docs/_build/html/.nojekyll
        
    - name: Upload documentation artifacts
      uses: actions/upload-artifact@v4
      with:
        name: documentation
        path: docs/_build/html/
        retention-days: 7
  
  deploy:
    needs: build-docs
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    steps:
    - name: Download documentation artifacts
      uses: actions/download-artifact@v4
      with:
        name: documentation
        path: ./docs-html

    - name: Fetch nightly status.json from nightly-status branch
      # The nightly-health workflow maintains a single-file orphan branch
      # (nightly-status) containing status.json.  Fetch it via the GitHub
      # contents API so no checkout is required.  Silently omitted on the
      # first docs deploy before any nightly run has pushed the branch.
      run: |
        if content=$(gh api \
            "repos/${{ github.repository }}/contents/status.json?ref=nightly-status" \
            --jq '.content' 2>/dev/null); then
          printf '%s' "$content" | base64 -d > ./docs-html/status.json
          echo "status.json merged into docs"
        else
          echo "No nightly-status branch yet; status.json omitted"
        fi
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    - name: Setup Pages
      uses: actions/configure-pages@v4
      
    - name: Upload artifact for Pages
      uses: actions/upload-pages-artifact@v3
      with:
        path: ./docs-html
        
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4