fix: prevent gh-pages repo bloat from doc preview artifacts

.github/workflows/pages.yml

@@ -23,33 +23,55 @@ permissions:
 
 jobs:
   build-docs:
+    if: github.event.action != 'closed'
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/ubuntu-setup
       - name: Build docs
         run: pip install nox uv && nox -s docs
       - name: Upload docs artifact
-        if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
         uses: actions/upload-artifact@v4
         with:
           name: docs-html
           path: docs/build/html
+          retention-days: 1
+
+  changes:
+    if: github.event_name == 'pull_request' && github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+              - 'modelopt/**'
+              - '.github/workflows/pages.yml'
 
   deploy-preview:
-    if: github.event_name == 'pull_request'
+    if: |
+      always() &&
+      github.event_name == 'pull_request' &&
+      (github.event.action == 'closed' || needs.changes.outputs.docs == 'true')
+    needs: [build-docs, changes]
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 10
     # Per-PR concurrency without cancel-in-progress so 'closed' cleanup always runs
     concurrency:
       group: pr-preview-${{ github.event.pull_request.number }}
     steps:
       - uses: actions/checkout@v6
-      - uses: ./.github/actions/ubuntu-setup
-      - name: Build docs
+      - name: Download docs artifact
         if: github.event.action != 'closed'
-        run: pip install nox uv && nox -s docs
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/build/html
       - name: Deploy / remove PR preview
         uses: rossjrw/pr-preview-action@v1
         with:
@@ -70,5 +92,6 @@ jobs:
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: docs/build/html
+          single-commit: true
           # Preserve PR preview subdirectories deployed by the deploy-preview job
           clean-exclude: pr-preview

noxfile.py

@@ -164,6 +164,8 @@ def docs(session):
     with session.chdir("docs"):
         session.run(
             "sphinx-build",
+            "-d",
+            "/tmp/doctrees",
             "source",
             "build/html",
             "--fail-on-warning",