docs.yml

name: Documentation

on:
  push:
    branches:
      - main
    tags: '*'
  pull_request:
  workflow_dispatch:
    inputs:
      deploy_tag:
        description: 'Tag to deploy docs for (e.g., v0.16.0). Leave empty for a dev build.'
        required: false
        type: string

permissions:
  packages: write
  contents: write
  statuses: write  # Used to report documentation build statuses

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# We need spack so that we can install palace for the tutorials
env:
  SPACK_VERSION: develop
  REGISTRY: ghcr.io/awslabs/palace
  GITHUB_USER: ${{ github.actor }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  # Filter to allow skipping the build if no relevant changes occurred. Tag pushes and
  # manual triggers always build (tags must deploy versioned docs, and workflow_dispatch
  # is intentional).
  filter:
    runs-on: ubuntu-latest
    outputs:
      should_build: ${{ steps.decide.outputs.should_build }}
    steps:
      - uses: actions/checkout@v6
      - uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            test:
              - 'palace/**'
              - 'cmake/**'
              - 'docs/**'
              - 'extern/**'
              - 'examples/**'
              - 'spack_repo/**'
              - '.github/workflows/docs.yml'
      - name: Decide whether to build
        id: decide
        env:
          GITHUB_REF: ${{ github.ref }}
          EVENT_NAME: ${{ github.event_name }}
          FILTER_TEST: ${{ steps.filter.outputs.test }}
        run: |
          if [[ "$GITHUB_REF" == refs/tags/* ]] || [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
            echo "should_build=true" >> "$GITHUB_OUTPUT"
          else
            echo "should_build=${FILTER_TEST}" >> "$GITHUB_OUTPUT"
          fi

  build-docs:
    needs: filter
    runs-on: palace_ubuntu-latest_16-core
    steps:
      - uses: actions/checkout@v6
        if: needs.filter.outputs.should_build == 'true'
        with:
          ref: ${{ inputs.deploy_tag || github.ref }}

      - name: Setup Spack
        if: needs.filter.outputs.should_build == 'true'
        uses: spack/setup-spack@v3
        with:
          # Pin to the Spack 1.2 release series (matching the self-hosted
          # runners) instead of the moving `develop` branch. spack@1.2 pairs
          # with the spack-packages releases/v2026.06 repo (see repos.yaml).
          spack_ref: releases/v1.2
          packages_ref: releases/v2026.06
          buildcache: true
          color: true

          
      - name: Patch Spack package.pys for known problems
        if: needs.filter.outputs.should_build == 'true'
        shell: bash
        run: |
          PALACE_DIR=$PWD
          cd $(spack location --repo builtin)
          for patch in "$PALACE_DIR"/spack_repo/patches/*.diff; do
            if [ -f "$patch" ]; then
              if ! git apply --check "$patch" 2>/dev/null; then
                echo "Cannot apply $patch (PR may have already been merged)"
                echo "Please remove $patch from the Palace repo if the PR was merged"
              else
                echo "Applying patch: $patch"
                git apply "$patch"
              fi
            fi
          done
  
          # Workaround for https://github.com/spack/spack/issues/51505
          ln -s "$(spack location --repo builtin)"/packages/mfem "$PALACE_DIR"/spack_repo/local/packages/
  
      - name: Setup Environment
        if: needs.filter.outputs.should_build == 'true'
        run: |
          # Spack.yaml with most / all settings configured
          cat << EOF > spack.yaml
          spack:
            specs:
              - local.palace@develop # we install this without a cache each time
            view: false
            config:
              install_tree:
                root: /opt/spack
                padded_length: false
            concretizer:
              reuse: false
              unify: true
              targets:
                granularity: generic
            packages:
              petsc:
                require: ~hdf5
            repos:
            - spack_repo/local
            mirrors:
              spack:
                binary: true
                url: https://binaries.spack.io/${SPACK_VERSION}
              local-buildcache:
                binary: true
                url: oci://${{ env.REGISTRY }}-${SPACK_VERSION}
                signed: false
                access_pair:
                  id_variable: GITHUB_USER
                  secret_variable: GITHUB_TOKEN
          EOF

      - name: Configure External Packages
        if: needs.filter.outputs.should_build == 'true'
        run: |
          # These cause build issues if built as externals
          #   - python : often distributed python isn't feature complete / not all dependencies get detected
          #   - OpenSSL / OpenSSH : since they are in /usr, spack struggles. It's common to rebuild these
          #   - ncurses / bzip2 / xz / curl : caused build issues. We pull these from GHCR cache after first build
          spack -e . external find --all \
            --exclude openssl \
            --exclude openssh \
            --exclude python \
            --exclude ncurses \
            --exclude bzip2 \
            --exclude xz \
            --exclude curl

      - name: Configure Compilers for Spack
        if: needs.filter.outputs.should_build == 'true'
        run: spack -e . compiler find && spack -e . compiler list

      - name: Configure Binary Mirror Keys for Spack
        if: needs.filter.outputs.should_build == 'true'
        run: spack -e . buildcache keys -y --install --trust

      - name: Bootstrap Spack
        if: needs.filter.outputs.should_build == 'true'
        run: spack  -e . bootstrap now

      - name: Concretize Spack
        if: needs.filter.outputs.should_build == 'true'
        env:
          PALACE_REF: ${{ github.head_ref || github.ref_name }}
        run: |
          # Using `spack develop` in order to have an in-source build
          PALACE_REF="${PALACE_REF//\//-}"
          spack -e . develop --path=$(pwd) local.palace@git."${PALACE_REF}"=develop
          spack -e . concretize -f

        # Relies on cache-hit(s)
      - name: Build Dependencies
        if: needs.filter.outputs.should_build == 'true'
        run: |
          spack -e . install --only-concrete --no-check-signature --fail-fast --show-log-on-error --include-build-deps --only dependencies

        # Explicitly not using cache to get latest develop
      - name: Build Palace
        if: needs.filter.outputs.should_build == 'true'
        run: |
          spack -e . install --only-concrete --show-log-on-error --only package --keep-stage --no-cache
        # If you want to use the branch-local source instead (should we always do this?)
        # spack -e . develop --path=$(pwd) palace@git."${{ github.head_ref || github.ref_name }}"=develop

      - uses: julia-actions/setup-julia@v2
        if: needs.filter.outputs.should_build == 'true'
        with:
          version: '1'

      - uses: julia-actions/cache@v3
        if: needs.filter.outputs.should_build == 'true'

      - name: Build and deploy
        if: needs.filter.outputs.should_build == 'true'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          DEPLOY_TAG: ${{ inputs.deploy_tag }}
        run: |
          # For workflow_dispatch with deploy_tag, override the runner's immutable
          # GITHUB_* env vars so Documenter.jl sees a tag push.
          if [[ -n "${DEPLOY_TAG}" ]]; then
            export GITHUB_EVENT_NAME=push
            export GITHUB_REF="refs/tags/${DEPLOY_TAG}"
            export GITHUB_REF_TYPE=tag
            export GITHUB_REF_NAME="${DEPLOY_TAG}"
          fi
          eval $(spack -e . load --sh palace)
          julia --project=docs -e 'using Pkg; Pkg.instantiate()'
          julia --project=docs --color=yes docs/make.jl

      - name: Verify stable docs deployment
        if: >-
          needs.filter.outputs.should_build == 'true' &&
          (startsWith(github.ref, 'refs/tags/') || inputs.deploy_tag != '')
        env:
          TAG_REF: ${{ inputs.deploy_tag || github.ref_name }}
        run: |
          TAG="${TAG_REF}"
          VERSION="${TAG#v}"
          git fetch origin gh-pages --depth=1
          STABLE=$(git show origin/gh-pages:stable)
          if [[ "$STABLE" != *"$VERSION"* ]]; then
            echo "::error::stable points to '$STABLE', expected '$VERSION'"
            exit 1
          fi

      - uses: actions/upload-artifact@v7
        if: needs.filter.outputs.should_build == 'true'
        with:
          name: docs
          path: docs/build/
          retention-days: 7

      # Push built binaries, even if the build fails
      # NOTE: This might fail as external fork PRs can't push to GHCR.
      - name: Push to GHCR cache
        if: |
          needs.filter.outputs.should_build == 'true' &&
          !cancelled() &&
          (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
        run: spack -e . buildcache push --force --with-build-dependencies --unsigned --update-index local-buildcache || true