docs.yml

name: Documentation

on:
  push:
    branches:
      - main
    tags: '*'
  pull_request:
  merge_group:

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

jobs:
  # Merge-queue fast path: reuse the doc build from an already-green PR head
  # when the merge group is byte-identical to it (see
  # .github/should_skip_merge_queue.sh).
  decide:
    name: decide
    runs-on: ubuntu-latest
    permissions:
      contents: read
      checks: read
      pull-requests: read
      statuses: read
    outputs:
      skip: ${{ steps.decide.outputs.skip }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: decide
        env:
          GH_TOKEN: ${{ github.token }}
          MERGE_GROUP_HEAD_REF: ${{ github.event.merge_group.head_ref }}
          MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
        run: |
          if .github/should_skip_merge_queue.sh "docbuild"; then
            echo "Merge-queue doc build skipped: reusing this PR's green check."
            echo "skip=true" >> "$GITHUB_OUTPUT"
          else
            echo "skip=false" >> "$GITHUB_OUTPUT"
          fi

  docbuild:
    needs: decide
    if: needs.decide.outputs.skip != 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
      - uses: julia-actions/setup-julia@v3
        with:
          version: '1.11'
      - uses: julia-actions/cache@v3
      - name: Install dependencies
        shell: julia --project=docs {0}
        run: |
          using Pkg
          Pkg.develop(PackageSpec(path="."))
          Pkg.instantiate()
      - name: Build and deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
        run: julia --project=docs/ docs/make.jl

  comment:
    needs: docbuild
    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - name: Post or update preview link
        uses: actions/github-script@v9
        with:
          script: |
            const pr = context.issue.number;
            const owner = context.repo.owner;
            const repo = context.repo.repo;
            const url = `https://${owner.toLowerCase()}.github.io/${repo}/previews/PR${pr}/`;
            const marker = '<!-- docs-preview-comment -->';
            const body = `${marker}\n📖 Docs preview for this PR: ${url}`;

            const { data: comments } = await github.rest.issues.listComments({
              owner, repo, issue_number: pr, per_page: 100,
            });
            const existing = comments.find(c => c.body?.includes(marker));
            if (existing) {
              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
            } else {
              await github.rest.issues.createComment({ owner, repo, issue_number: pr, body });
            }

  # Single required status check for the doc build. Set THIS ("docs-required")
  # as the required check instead of "docbuild", so a reused merge-queue build
  # (docbuild skipped) still reports green.
  docs-required:
    name: docs-required
    needs: [decide, docbuild]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - run: |
          if [[ "${{ needs.decide.result }}" != "success" ]]; then
            echo "decide job did not succeed"; exit 1
          fi
          if [[ "${{ needs.docbuild.result }}" == "success" ]]; then
            echo "doc build passed"; exit 0
          fi
          if [[ "${{ needs.docbuild.result }}" == "skipped" && \
                "${{ needs.decide.outputs.skip }}" == "true" ]]; then
            echo "doc build reused from an already-green PR head"; exit 0
          fi
          echo "doc build did not pass (result=${{ needs.docbuild.result }})"
          exit 1