Make a document preview for PRs

Make it much easier for reviewing changes on docs.

Signed-off-by: Shengliang Xu <shengliangx@nvidia.com>

Author: shengliangxu

.github/workflows/pages.yml

@@ -14,11 +14,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
   cancel-in-progress: true
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+# contents: write required to push to gh-pages branch
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
 jobs:
   build-docs:
@@ -30,18 +28,26 @@ jobs:
       - name: Build docs
         run: pip install tox && tox -e build-docs
       - name: Upload docs artifact
-        if: github.event_name == 'push'
-        uses: actions/upload-pages-artifact@v4
+        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
 
   deploy-gh-pages:
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     needs: build-docs
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
+      - uses: actions/checkout@v6
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/build/html
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/build/html
+          # Preserve PR preview subdirectories deployed by pr-preview.yml
+          clean-exclude: pr-preview

.github/workflows/pr-preview.yml

@@ -0,0 +1,28 @@
+name: PR Docs Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    branches: [main, release/*, feature/*]
+
+# One preview deployment per PR; do not cancel so 'closed' cleanup always runs
+concurrency: pr-preview-${{ github.event.pull_request.number }}
+
+permissions:
+  contents: write       # push preview to gh-pages branch
+  pull-requests: write  # post/update preview URL comment on the PR
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ./.github/actions/ubuntu-setup
+      - name: Build docs
+        if: github.event.action != 'closed'
+        run: pip install tox && tox -e build-docs
+      - name: Deploy / remove PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/build/html