build-docs.yml

name: build-docs
on:
  push:
  workflow_dispatch:

env:
  CACHE_NUMBER: 0
  DEPLOY_BRANCH: gh-pages               # deployed docs branch

defaults:
  run:
    shell: bash -le {0}
jobs:
  build-sphinx-html:
    if: ((github.repository == 'tardis-sn/stardis') && (${{ github.head_ref || github.ref_name}} == 'main')) || (github.repository_owner != 'tardis-sn')
    # The above line makes this action run if it is either not on the upstream/main or the main branch of upstream/main.
    # If there is a better way to implement this, I'd like someone to please share.
    # The context to get the branch name is from https://stackoverflow.com/a/71158878
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v2
        
      - name: Setup Mambaforge
        uses: conda-incubator/setup-miniconda@v2
        with:
          miniforge-variant: Mambaforge
          miniforge-version: latest
          activate-environment: stardis
          use-mamba: true
      
      - name: Cache Environment Lockfile
        id: cache-env-lockfile
        uses: actions/cache@v3
        with:
          path: /usr/share/miniconda3/envs/stardis
          key: conda-linux-64-${{ hashFiles('conda-linux-64.lock') }}-${{ env.CACHE_NUMBER }}
                  
      - name: Update Conda Environment
        id: update-env
        run: |
          mamba update -n stardis --file conda-linux-64.lock
        if: steps.cache-env-lockfile.outputs.cache-hit != 'true'
        
      - name: Install TARDIS
        id: install-tardis
        # shell: bash -l {0}
        run: |
          pip install git+https://github.com/tardis-sn/tardis.git@release-2024.08.25
        
      - name: Install STARDIS
        id: install-stardis
        # shell: bash -l {0}
        run: |
          pip install -e .[docs]

      - name: Make Sphinx HTML
        id: make-sphinx-html
        run: |
          make -C docs html
          
      - 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: Deploy ${{ env.DEST_DIR }}
        uses: peaceiris/actions-gh-pages@v3
        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'