build and preview docs on PR

Author: SwayamInSync

.github/workflows/build_docs.yml

@@ -4,18 +4,21 @@ on:
   push:
     branches:
       - main
+  pull_request:
+    paths:
+      - 'quaddtype/**'
   workflow_dispatch:  # Make sure this job can be triggered manually
 
+# Allow only one concurrent deployment per PR/branch
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/configure-pages@v5
       - uses: actions/setup-python@v6
         with:
           python-version: '3.13'
@@ -33,11 +36,92 @@ jobs:
           cd quaddtype/
           python -m pip install ."[docs]"
           cd docs/
-          sphinx-build -b html . _build/html/quaddtype
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+          sphinx-build -b html . _build/html
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
         with:
+          name: docs-html
           path: './quaddtype/docs/_build/html'
+
+  # Deploy main docs to GitHub Pages (only on push to main)
+  deploy-main:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: './docs-html'
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: './docs-html'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+
+  # Deploy PR preview (only on pull requests)
+  deploy-preview:
+    if: github.event_name == 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: './docs-html'
+      - name: Deploy PR Preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: './docs-html'
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          action: auto
+      - name: Comment PR with preview URL
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const previewUrl = `https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.pull_request.number }}/`;
+            const body = `📚 **Documentation Preview**\n\nPreview URL: ${previewUrl}\n\n_This preview will be automatically updated when you push new commits._`;
+            
+            // Check if we already commented
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            
+            const botComment = comments.find(comment => 
+              comment.user.type === 'Bot' && comment.body.includes('Documentation Preview')
+            );
+            
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: body
+              });
+            }