Add stable branch syncing and webhook for readthedocs build triggering (#89)

This change adds a periodic GitHub Action that pulls the main branch, checks out the latest release of Slang for the slang submodule (instead of using the master branch), and then force pushes the updated main branch and release submodule to the branch "stable", which will be used for the stable branch of the readthedocs site.

readthedocs does not recognize pushes from GitHub Actions bots, so the final step is to post a token to the site's webhook to directly trigger a new build. This change also adds that step to the submodule sync action.

Author: aidanfnv

.github/workflows/sync-stable-branch.yml

@@ -0,0 +1,83 @@
+name: Sync Stable Branch with Slang Release
+
+on:
+  schedule:
+    # Run at 3:00 AM UTC every day
+    - cron: '0 3 * * *'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  sync-stable-branch:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v4
+        with:
+          ref: main # Explicitly checkout main
+          # Fetch all history for all branches and tags
+          fetch-depth: 0
+          # Get submodules, but don't update them yet
+          submodules: 'recursive'
+
+      - name: Set up Git
+        run: |
+          git config --global user.name 'Read the Docs Bot'
+          git config --global user.email 'rtd-bot@shader-slang.com'
+
+      - name: Get latest slang release tag
+        id: slang_latest_tag
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Provide token explicitly for gh
+        run: |
+          LATEST_TAG=$(gh release view --repo shader-slang/slang --json tagName --jq .tagName)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "Failed to fetch latest slang release tag using gh"
+            exit 1
+          fi
+          echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+          echo "Fetched latest slang tag: $LATEST_TAG"
+
+      - name: Update slang submodule to latest release tag
+        run: |
+          pushd docs/external/slang
+          git fetch --tags origin
+          git checkout ${{ steps.slang_latest_tag.outputs.tag }}
+          popd
+          echo "Checked out tag ${{ steps.slang_latest_tag.outputs.tag }} in docs/external/slang"
+
+      - name: Check for changes
+        id: check_changes
+        run: |
+          # Only stage the slang submodule, as the others are already updated
+          git add docs/external/slang
+          
+          # Check if the index differs from HEAD
+          # git diff --cached --quiet exits 0 if no diff, 1 if diff
+          if ! git diff --cached --quiet; then
+            echo "Changes detected in submodule references."
+            echo "changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "No changes detected in submodule references."
+            echo "changes=false" >> $GITHUB_OUTPUT
+            # If no changes, reset the index in case unrelated changes were staged
+            git reset HEAD --quiet
+          fi
+
+      - name: Commit and push changes to stable branch
+        if: steps.check_changes.outputs.changes == 'true'
+        run: |
+          git commit -m "Sync stable to release (slang@${{ steps.slang_latest_tag.outputs.tag }})"
+          git push origin HEAD:stable --force
+          echo "Committed and force-pushed updates to stable branch."
+
+      - name: Trigger Read the Docs Build on stable branch update
+        if: steps.check_changes.outputs.changes == 'true'
+        env:
+          RTD_WEBHOOK_SECRET: ${{ secrets.RTD_WEBHOOK_SECRET }}
+        run: |
+          curl -X POST \
+               -H "Authorization: token $RTD_WEBHOOK_SECRET" \
+               https://readthedocs.org/api/v2/webhook/slang-documentation/296117/
+          echo "Triggered Read the Docs build."

.github/workflows/update-submodules.yml

@@ -22,8 +22,8 @@ jobs:
 
       - name: Set up Git
         run: |
-          git config --global user.name 'github-actions'
-          git config --global user.email 'github-actions@github.com'
+          git config --global user.name 'Read the Docs Bot'
+          git config --global user.email 'rtd-bot@shader-slang.com'
 
       - name: Get default branch
         id: default_branch
@@ -42,15 +42,31 @@ jobs:
       - name: Check if submodules changed
         id: check_changes
         run: |
-          if [[ -n "$(git status --porcelain)" ]]; then
+          git add -A
+          
+          # Check if the index differs from HEAD
+          # git diff --cached --quiet exits 0 if no diff, 1 if diff
+          if ! git diff --cached --quiet; then
+            echo "Changes detected in submodule references."
             echo "changes=true" >> $GITHUB_OUTPUT
           else
+            echo "No changes detected in submodule references."
             echo "changes=false" >> $GITHUB_OUTPUT
+            # If no changes, reset the index in case unrelated changes were staged
+            git reset HEAD --quiet
           fi
 
       - name: Commit and push changes
         if: steps.check_changes.outputs.changes == 'true'
         run: |
-          git add -A
           git commit -m "Auto-update submodules"
-          git push origin ${{ steps.default_branch.outputs.name }} 
+          git push origin ${{ steps.default_branch.outputs.name }}
+
+      - name: Trigger Read the Docs Build
+        if: steps.check_changes.outputs.changes == 'true'
+        env:
+          RTD_WEBHOOK_SECRET: ${{ secrets.RTD_WEBHOOK_SECRET }}
+        run: |
+          curl -X POST \
+               -H "Authorization: token $RTD_WEBHOOK_SECRET" \
+               https://readthedocs.org/api/v2/webhook/slang-documentation/296117/