docs_workflow.yml

name: CI/CD Release Workflow

on:
  push:
    branches: [main, legacy]

  release:
    types: [published]

env:
  PYTHON_VERSION: "3.14"

jobs:
  publish-docs:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -l {0}
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
          fetch-depth: 0

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

      - name: Cache pixi packages
        uses: actions/cache@v5
        env:
          # Increase this value to reset cache if deploy inputs have not changed in the workflow
          CACHE_NUMBER: 0
        with:
          path: |
            ~/.cache/rattler/cache
            ~/.pixi/bin
          key: ${{ runner.os }}-${{ env.PYTHON_VERSION }}-pixi-${{ env.CACHE_NUMBER }}-${{ hashFiles('deploy.py', 'deploy/**', 'pyproject.toml') }}

      - name: Install compass
        run: |
          git config --global url."https://github.com/".insteadOf "git@github.com:"
          ./deploy.py \
            --no-spack \
            --python ${{ env.PYTHON_VERSION }} \
            --recreate
          load_script=$(find . -maxdepth 1 -type f -name 'load_compass*.sh' | sort | tail -n 1)
          if [ -z "$load_script" ]; then
            echo "ERROR: no generated Compass load script found" >&2
            exit 1
          fi
          source "$load_script"

      - name: Build Sphinx Docs
        run: |
          load_script=$(find . -maxdepth 1 -type f -name 'load_compass*.sh' | sort | tail -n 1)
          source "$load_script"
          cd docs
          make html
      - name: Copy Docs and Commit
        run: |
          load_script=$(find . -maxdepth 1 -type f -name 'load_compass*.sh' | sort | tail -n 1)
          source "$load_script"
          cd docs
          # gh-pages branch must already exist
          git clone https://github.com/MPAS-Dev/compass.git --branch gh-pages --single-branch gh-pages
          # Make sure we're in the gh-pages directory.
          cd gh-pages
          # Create `.nojekyll` (if it doesn't already exist) for proper GH Pages configuration.
          touch .nojekyll
          # Add `index.html` to point to the `main` branch automatically.
          printf '<meta http-equiv="refresh" content="0; url=./main/index.html" />' > index.html
          # Replace the docs for the current branch or tag with the latest build.
          export DOCS_VERSION="${GITHUB_REF_NAME}"
          rm -rf ${DOCS_VERSION}
          mkdir ${DOCS_VERSION}
          cp -r ../_build/html/* ${DOCS_VERSION}
          # Configure git using GitHub Actions credentials.
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          # The second command will fail if no changes were present, so we ignore it
          git add .
          git commit -m "Update documentation" -a || true
      - name: Push Changes
        uses: ad-m/github-push-action@master
        with:
          branch: gh-pages
          directory: docs/gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          force: true