build-docs.yml

#  For more information about TARDIS pipelines, please refer to:
#
#    https://tardis-sn.github.io/tardis/contributing/development/continuous_integration.html

name: docs

on:
  push:
    branches:
      - master

  pull_request_target:
    branches:
      - master

    types:
      - opened
      - reopened
      - synchronize
      - labeled # requires the `build-docs` label
      - ready_for_review

  workflow_dispatch: # manual trigger

env:
  CACHE_NUMBER: 0 # increase to reset cache manually
  DEPLOY_BRANCH: gh-pages # deployed docs branch
  HDF5_USE_FILE_LOCKING: "FALSE" # disable file locking

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

defaults:
  run:
    shell: bash -l {0}

jobs:
  check-for-changes:
    runs-on: ubuntu-latest
    if: ${{ !github.event.pull_request.draft }}
    outputs:
      should-run: ${{ steps.check_conditions.outputs.should-run }}
    steps:
      - uses: actions/checkout@v4
        if: github.event_name != 'pull_request_target'

      - name: Checkout pull/${{ github.event.number }}
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}
        if: github.event_name == 'pull_request_target'

      - id: check_conditions
        name: Check conditions for running workflow
        run: |
          # Initialize should-run as false
          echo "should-run=false" >> $GITHUB_OUTPUT
          
          # Always run for push and workflow_dispatch
          if [[ "${{ github.event_name }}" == "push" ]] || [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            echo "should-run=true" >> $GITHUB_OUTPUT
            exit 0
          fi
          
          # For pull_request_target events
          if [[ "${{ github.event_name }}" == "pull_request_target" ]]; then
            # Check if docs directory has changes
            HAS_DOCS_CHANGES=false
            if git diff origin/master..."$(git rev-parse --abbrev-ref HEAD)" --name-only | cat | grep '^docs/' | grep -q .; then
              HAS_DOCS_CHANGES=true
              num_files=$(git diff --name-only origin/master...HEAD | grep '^docs/' | wc -l)
              echo "Changes found in documentation files: $num_files"
            else
              echo "No changes found in documentation files - will stop running the pipeline."
            fi
            
            # Check if PR has build-docs label
            HAS_BUILD_DOCS_LABEL=${{ contains(github.event.pull_request.labels.*.name, 'build-docs') }}
            
            if [[ "$HAS_DOCS_CHANGES" == "true" && "$HAS_BUILD_DOCS_LABEL" == "false" ]] || \
               [[ "$HAS_DOCS_CHANGES" == "false" && "$HAS_BUILD_DOCS_LABEL" == "true" ]]; then
              echo "should-run=true" >> $GITHUB_OUTPUT
            fi
          fi

  build-docs:
    runs-on: ubuntu-latest
    needs: check-for-changes
    if: needs.check-for-changes.outputs.should-run == 'true'
    steps:
      - uses: actions/checkout@v4
        if: github.event_name != 'pull_request_target'

      - name: Checkout pull/${{ github.event.number }}
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}
        if: github.event_name == 'pull_request_target'

      - uses: actions/checkout@v4
        with:
          repository: tardis-sn/tardis-regression-data
          path: tardis-regression-data
          lfs: true
          sparse-checkout: |
            atom_data/kurucz_cd23_chianti_H_He.h5

      - name: Setup environment
        uses: ./.github/actions/setup_env
        with:
          os-label: linux-64

      - name: Copy atom_data
        run: |
          mkdir -p ~/Downloads/tardis-data && cp -a ./tardis-regression-data/atom_data/. ~/Downloads/tardis-data

      - name: Install package
        run: pip install -e .

      - name: Install Sphinx extensions
        run: |
          pip install sphinxcontrib-googleanalytics

      - name: Build documentation
        run: cd docs/ && make html NCORES=auto

      - name: Set destination directory
        run: |
          BRANCH=$(echo ${GITHUB_REF#refs/heads/})
          if [[ $EVENT == push ]] || [[ $EVENT == workflow_dispatch ]]; then

            if [[ $BRANCH == $DEFAULT ]]; then
              echo "DEST_DIR=" >> $GITHUB_ENV
            else
              echo "DEST_DIR=branch/$BRANCH" >> $GITHUB_ENV
            fi

          elif [[ $EVENT == pull_request_target ]]; then
            echo "DEST_DIR=pull/$PR" >> $GITHUB_ENV

          else
            echo "Unexpected event trigger $EVENT"
            exit 1

          fi

          cat $GITHUB_ENV
        env:
          DEFAULT: ${{ github.event.repository.default_branch }}
          EVENT: ${{ github.event_name }}
          PR: ${{ github.event.number }}

      - name: Set clean branch option
        run: |
          if [[ $EVENT == workflow_dispatch ]]; then
            echo "CLEAN_BRANCH=true" >> $GITHUB_ENV

          else
            echo "CLEAN_BRANCH=false" >> $GITHUB_ENV

          fi

          cat $GITHUB_ENV
        env:
          EVENT: ${{ github.event_name }}

      - name: Deploy ${{ env.DEST_DIR }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.BOT_TOKEN }}
          publish_branch: ${{ env.DEPLOY_BRANCH }}
          publish_dir: ./docs/_build/html
          destination_dir: ${{ env.DEST_DIR }}
          keep_files: true
          force_orphan: ${{ env.CLEAN_BRANCH }}
          user_name: "TARDIS Bot"
          user_email: "tardis.sn.bot@gmail.com"

      - name: Find comment
        uses: peter-evans/find-comment@v1
        id: fc
        with:
          issue-number: ${{ github.event.number }}
          body-includes: Hi, human.
        if: always() && github.event_name == 'pull_request_target'

      - name: Post comment (success)
        uses: peter-evans/create-or-update-comment@v1
        with:
          token: ${{ secrets.BOT_TOKEN }}
          issue-number: ${{ github.event.number }}
          comment-id: ${{ steps.fc.outputs.comment-id }}
          edit-mode: replace
          body: |
            *\*beep\* \*bop\**

            Hi, human.

            The **`${{ github.workflow }}`** workflow has **succeeded** :heavy_check_mark:

            [**Click here**](${{ env.URL }}) to see your results.
        env:
          URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pull/${{ github.event.number }}/index.html
        if: success() && github.event_name == 'pull_request_target'

      - name: Post comment (failure)
        uses: peter-evans/create-or-update-comment@v1
        with:
          token: ${{ secrets.BOT_TOKEN }}
          issue-number: ${{ github.event.number }}
          comment-id: ${{ steps.fc.outputs.comment-id }}
          edit-mode: replace
          body: |
            *\*beep\* \*bop\**

            Hi, human.

            The **`${{ github.workflow }}`** workflow has **failed** :x:

            [**Click here**](${{ env.URL }}) to see the build log.
        env:
          URL: https://github.com/${{ github.repository_owner }}/${{ github.event.repository.name }}/actions/runs/${{ github.run_id }}?check_suite_focus=true
        if: failure() && github.event_name == 'pull_request_target'