Streamlined Build docs workflow (#423)

* Update build docs workflow * Add clean docs worklfow * Removing redundant default shell step * Update deployment step * Update url
tardis-sn · Feb 6, 2025 · 5f6bfe6 · 5f6bfe6
1 parent c250524
commit 5f6bfe6
Show file tree

Hide file tree

Showing 2 changed files with 117 additions and 20 deletions.
diff --git a/.github/workflows/clean-docs.yml b/.github/workflows/clean-docs.yml
@@ -0,0 +1,62 @@
+#  For more information about TARDIS pipelines, please refer to:
+#
+#    https://tardis-sn.github.io/tardis/contributing/development/continuous_integration.html
+
+name: clean-docs
+
+on:
+  delete:
+    branches: # remove deleted branches
+      - "*"
+
+  pull_request_target: # remove closed or merged pull requests
+    branches:
+      - "*"
+    types:
+      - closed
+
+env:
+  DEPLOY_BRANCH: gh-pages #  deployed docs branch
+
+jobs:
+  clean:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set folder to delete
+        run: |
+          if [[ $EVENT == delete ]]; then
+            echo "DEST_DIR=$EVENT_TYPE/$EVENT_REF" >> $GITHUB_ENV
+
+          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:
+          PR: ${{ github.event.number }}
+          EVENT: ${{ github.event_name }}
+          EVENT_REF: ${{ github.event.ref }}
+          EVENT_TYPE: ${{ github.event.ref_type }}
+
+      - name: Clean ${{ env.DEST_DIR }}
+        run: |
+          git fetch origin ${{ env.DEPLOY_BRANCH }}
+          git checkout ${{ env.DEPLOY_BRANCH }}
+          git config user.name "TARDIS Bot"
+          git config user.email [email protected]
+
+          if [[ -d $DEST_DIR ]]; then
+            git rm -rf $DEST_DIR
+            git commit -m "clean $DEST_DIR"
+            git push
+
+          else
+            echo "$DEST_DIR does not exist"
+
+          fi
diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml
@@ -17,12 +17,10 @@ on:
       - opened
       - reopened
       - synchronize
-      - labeled                         # requires the `build-docs` label
+      - labeled # requires the `build-docs` label
+      - ready_for_review
 
-  workflow_dispatch:                    # manual trigger
-
-  schedule:
-    - cron: '0 0 * * 0' # run at midnight every Sunday
+  workflow_dispatch: # manual trigger
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
@@ -36,16 +34,55 @@ env:
   CMFGEN_DB_VER: atomic_data_15nov16.tar.gz
   DEPLOY_BRANCH: gh-pages               # deployed docs branch
 
-jobs:
+defaults:
+  run:
+    shell: bash -l {0}
 
-  build:
-    if: github.event_name == 'push' ||
-        github.event_name == 'workflow_dispatch' ||
-        (github.event_name == 'pull_request_target' &&
-        contains(github.event.pull_request.labels.*.name, 'build-docs'))
+jobs:
+  check-for-changes:
     runs-on: ubuntu-latest
+    if: ${{ !github.event.pull_request.draft }}
+    outputs:
+      trigger-check-outcome: ${{ steps.trigger_check.outcome }}
+      docs-check-outcome: ${{ steps.docs_check.outcome }}
     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'
+
+      - name: Check for trigger by push event, manual dispatch, build-docs label on a PR
+        id: trigger_check
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request_target' && contains(github.event.pull_request.labels.*.name, 'build-docs')
+        run: |
+          echo "Building docs as a test."
+          exit 0
+        continue-on-error: true
 
+      - name: Check for changes in documentation
+        run: |
+          if git diff origin/master..."$(git rev-parse --abbrev-ref HEAD)" --name-only | cat | grep '^docs/' | grep -q .; then
+              num_files=$(git diff --name-only origin/master...HEAD | grep '^docs/' | wc -l)
+              echo "Changes found in documentation files: $num_files"
+              exit 0
+          else
+              echo "No changes found in documentation files - will stop running the pipeline."
+              exit 1
+          fi
+        id: docs_check
+        if: steps.trigger_check.outcome != 'success'
+        continue-on-error: true
+
+  build-docs:
+    runs-on: ubuntu-latest
+    needs: check-for-changes
+    if: needs.check-for-changes.outputs.trigger-check-outcome == 'success' || needs.check-for-changes.outputs.docs-check-outcome == 'success'
+    steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
@@ -84,12 +121,10 @@ jobs:
           environment-name: carsus
 
       - name: Install package
-        shell: bash -l {0}
         run: pip install -e .
 
       - name: Build documentation
-        shell: bash -l {0}
-        run: cd docs/; make html
+        run: cd docs/ && make html NCORES=auto
 
       - name: Set destination directory
         run: |
@@ -132,16 +167,16 @@ jobs:
           EVENT: ${{ github.event_name }}
 
       - name: Deploy ${{ env.DEST_DIR }}
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_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: 'Github Actions'
-          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
+          user_name: "TARDIS Bot"
+          user_email: "tardis.sn.bot@gmail.com"
 
       - name: Find comment
         uses: peter-evans/find-comment@v1
@@ -164,10 +199,10 @@ jobs:
             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 }}/
+          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)
@@ -183,7 +218,7 @@ jobs:
             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