force jobs to run in series; add notes

Author: jeffjennings

.github/workflows/deploy.yaml

@@ -83,6 +83,25 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./public
 
+  pre_index:
+    # this job effectively tests the indexing before the next job that
+    # clears it (so that the site doesn't end up empty if the indexing fails)
+    runs-on: ubuntu-latest
+    needs: deploy
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: 3.12
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -r deployment/requirements.txt
+
       - name: Pre-index tutorials
         id: preindex
         env:
@@ -94,9 +113,27 @@ jobs:
             public/tutorials \
             https://learn.astropy.org/tutorials
 
+  clear_index:
+    # this job clears all records in the Algolia index to ensure new content appears on
+    # the site
+    runs-on: ubuntu-latest
+    needs: pre_index
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: 3.12
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -r deployment/requirements.txt
+
       - name: Clear Algolia index
         id: clearindex
-        if: steps.preindex.outcome == 'success'
         env:
           ALGOLIA_ID: ${{ secrets.ALGOLIA_ID }}
           ALGOLIA_KEY: ${{ secrets.ALGOLIA_KEY }}
@@ -107,8 +144,24 @@ jobs:
             --algolia-key "$ALGOLIA_KEY" \
             --index "$ALGOLIA_INDEX"
 
+  index:
+    runs-on: ubuntu-latest
+    needs: clear_index
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: 3.12
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -r deployment/requirements.txt
+
       - name: Index tutorials
-        if: steps.clearindex.outcome == 'success'
         env:
           ALGOLIA_ID: ${{ secrets.ALGOLIA_ID }}
           ALGOLIA_KEY: ${{ secrets.ALGOLIA_KEY }}
@@ -119,6 +172,8 @@ jobs:
             https://learn.astropy.org/tutorials
 
       - name: Index guides
+        # continue on error because guides can be externally hosted; avoid a change to
+        # them from preventing the tutorials updating on the site
         continue-on-error: true
         env:
           ALGOLIA_ID: ${{ secrets.ALGOLIA_ID }}