docs-dev.yml

name: Deploy dev documentation

on:
  push:
    branches:
      - main
  workflow_dispatch:

# Ensure only one deployment runs at a time
concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594  # v2.16.0
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8  # v6.0.1
        with:
          fetch-depth: 1

      - name: Install uv
        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0
        with:
          version: "0.11.4"

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version-file: ".python-version"

      - name: Install pandoc
        uses: pandoc/actions/setup@86321b6dd4675f5014c611e05088e10d4939e09e  # v1.1.1

      - name: Build Sphinx documentation
        run: uv run --extra docs --extra sim sphinx-build -j auto -b html docs docs/_build/html
        env:
          NEWTON_REQUIRE_PANDOC: "1"

      - name: Deploy to gh-pages /latest/
        run: |
          set -e  # Exit on any error

          git config user.email "actions@github.com"
          git config user.name "GitHub Actions"

          # Save built docs and 404 template outside the repo before switching branches
          mv docs/_build/html /tmp/docs-latest
          cp docs/_static/gh-pages-404.html /tmp/gh-pages-404.html

          # Switch to gh-pages branch (check existence first to avoid masking other fetch errors)
          # Distinguish "branch not found" (exit 2) from fatal errors (exit 128)
          # to prevent a transient failure from creating an orphan that overwrites
          # all existing versioned docs on the force push below.
          ls_remote_rc=0
          git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1 || ls_remote_rc=$?

          if [ "$ls_remote_rc" -eq 0 ]; then
            git fetch --depth=1 origin gh-pages:gh-pages
            git checkout gh-pages
          elif [ "$ls_remote_rc" -eq 2 ]; then
            echo "Creating new gh-pages branch"
            git checkout --orphan gh-pages
            git rm -rf . || true
          else
            echo "::error::git ls-remote failed with exit code $ls_remote_rc — aborting to prevent data loss"
            exit 1
          fi

          # Remove old /latest/ and replace with new build
          rm -rf latest
          mv /tmp/docs-latest latest

          # Deploy custom 404 page for redirecting old non-versioned URLs
          cp /tmp/gh-pages-404.html 404.html

          # Ensure .nojekyll exists
          touch .nojekyll

          # Check gh-pages size (warn if approaching GitHub Pages 1GB limit)
          SIZE_KB=$(du -sk --exclude=.git . | cut -f1)
          SIZE_MB=$((SIZE_KB / 1024))
          echo "Current gh-pages size: ${SIZE_MB}MB"
          if [ "$SIZE_MB" -gt 800 ]; then
            echo "::warning::gh-pages branch is ${SIZE_MB}MB, approaching GitHub Pages 1GB limit. Consider pruning old versions."
          fi

          # Stage new/modified files. git checkout --orphan below preserves the
          # full index from gh-pages, so all previously tracked files (e.g.
          # versioned release docs) are also included in the deploy commit.
          git add latest 404.html .nojekyll

          # Reset to an orphan commit to prevent unbounded history growth.
          # gh-pages is a deployment target, not a historical record.
          git checkout --orphan gh-pages-deploy
          git commit -m "Deploy dev docs from main@${GITHUB_SHA::8}"
          git push origin HEAD:gh-pages --force