docs-release.yml

name: Deploy release documentation

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to build (e.g., 1.0.0)'
        required: true
        type: string

# 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: Set version from tag or input
        id: version
        env:
          EVENT_NAME: ${{ github.event_name }}
          INPUT_VERSION: ${{ inputs.version }}
        run: |
          if [ "$EVENT_NAME" = "push" ]; then
            VERSION="${GITHUB_REF#refs/tags/v}"
          else
            VERSION="$INPUT_VERSION"
          fi
          echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
          echo "Version: $VERSION"

          # Only deploy docs for stable releases (strict semver X.Y.Z)
          # Pre-release tags (e.g., 1.0.0-rc.1, 1.0.0-beta) are skipped entirely
          if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "SHOULD_DEPLOY=true" >> $GITHUB_OUTPUT
            echo "Stable release detected: will deploy docs"
          else
            echo "SHOULD_DEPLOY=false" >> $GITHUB_OUTPUT
            echo "Pre-release detected: skipping documentation deployment"
          fi

      - name: Install uv
        if: steps.version.outputs.SHOULD_DEPLOY == 'true'
        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0
        with:
          version: "0.11.26"

      - name: Set up Python
        if: steps.version.outputs.SHOULD_DEPLOY == 'true'
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version-file: ".python-version"

      - name: Install pandoc
        if: steps.version.outputs.SHOULD_DEPLOY == 'true'
        uses: pandoc/actions/setup@86321b6dd4675f5014c611e05088e10d4939e09e  # v1.1.1

      - name: Build Sphinx documentation
        if: steps.version.outputs.SHOULD_DEPLOY == 'true'
        # `-d docs/_build/doctrees` keeps Sphinx's pickled doctree cache out of
        # the published html/ tree (GH-2726): it is build-only state, ~25 MB of
        # non-deterministic bytes that no browser loads.
        run: uv run --extra docs --extra sim sphinx-build -j auto -d docs/_build/doctrees -b html docs docs/_build/html
        env:
          NEWTON_REQUIRE_PANDOC: "1"

      - name: Deploy to gh-pages
        if: steps.version.outputs.SHOULD_DEPLOY == 'true'
        env:
          VERSION: ${{ steps.version.outputs.VERSION }}
        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-release
          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

          # Deploy version directory (remove old if rebuilding)
          rm -rf "$VERSION"
          mv /tmp/docs-release "$VERSION"

          # Update stable/ directory (copy, not symlink - symlinks unreliable on GH Pages)
          rm -rf stable
          cp -r "$VERSION" stable

          # Update switcher.json (script is in the main branch, not gh-pages)
          # Fetch main ref so origin/main is available (shallow checkout only has the tag)
          git fetch --depth=1 origin main
          git show origin/main:scripts/ci/update_docs_switcher.py > /tmp/update_docs_switcher.py
          uv run --no-project /tmp/update_docs_switcher.py "$VERSION"
          rm -f switcher.json.bak

          # Ensure root index.html redirect exists
          {
            echo '<!DOCTYPE html>'
            echo '<html>'
            echo '<head>'
            echo '  <meta charset="utf-8">'
            echo '  <title>Redirecting to Newton Documentation</title>'
            echo '  <meta http-equiv="refresh" content="0; url=stable/">'
            echo '  <link rel="canonical" href="https://newton-physics.github.io/newton/stable/">'
            echo '</head>'
            echo '<body>'
            echo '  <p>Redirecting to <a href="stable/">Newton Documentation</a>...</p>'
            echo '</body>'
            echo '</html>'
          } > index.html

          # 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.
          # other versioned docs, latest/) are also included in the deploy commit.
          git add "$VERSION" stable switcher.json index.html 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 "Release v$VERSION documentation"
          git push origin HEAD:gh-pages --force