ci: add docs preview to PR CI (#6351)

Signed-off-by: Neal Vaidya <nealv@nvidia.com>

.github/filters.yaml

@@ -19,6 +19,7 @@ all:
 docs:
   - 'docs/**'
   - 'fern/**'
+  - '.github/workflows/fern-docs.yml'
   - '**/*.md'
   - '**/*.txt'
   - '**/.gitignore'

.github/workflows/fern-docs.yml

@@ -18,18 +18,19 @@
 # This workflow handles all Fern documentation automation:
 #
 # 1. LINT (PRs): Validates Fern configuration and checks for broken links
-#    - Triggers on pull requests when docs/** files change
+#    - Triggers on PRs when docs/** files change
 #    - Runs `fern check` and `fern docs broken-links`
 #
-# 2. SYNC dev (push to main): Syncs docs/ from main to fern/ on docs-website branch
-#    - Triggers on push to main when docs/** files change
-#    - Preserves versioned documentation snapshots on docs-website branch
-#    - Publishes docs to Fern after syncing
+# 2. SYNC & PUBLISH/PREVIEW: Syncs docs/ from source branch to fern/ on docs-website
+#    - Triggers on push to main or PRs when docs/** files change
+#    - On main: commits and pushes to docs-website, then publishes via `fern generate --docs`
+#    - On PRs: generates a preview URL via `fern generate --docs --preview` and comments on PR
+#    - Preserves versioned documentation (products[0]) from docs-website's docs.yml
 #
 # 3. VERSION RELEASE (tags): Creates versioned documentation snapshot
 #    - Triggers on new version tags (vX.Y.Z format)
-#    - Creates pages-vX.Y.Z/ directory on docs-website branch
-#    - Updates docs.yml with new version entry
+#    - Creates fern/pages-vX.Y.Z/ directory on docs-website branch
+#    - Updates fern/docs.yml with new version entry
 #    - Publishes docs to Fern after releasing
 #
 # Note: The publish step is included inline because pushes made with GITHUB_TOKEN
@@ -55,6 +56,7 @@ on:
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   # Detect changed files for conditional job execution
@@ -138,23 +140,33 @@ jobs:
         run: fern docs broken-links
 
   #############################################################################
-  # SYNC dev - Run on push to main when docs/** files change
+  # SYNC & PUBLISH/PREVIEW - Syncs docs content to docs-website structure
+  # On main: commits, pushes, and publishes to Fern
+  # On PRs: generates a preview URL and comments on the PR
   #############################################################################
 
-  sync-dev:
-    name: Sync dev to docs-website
+  preview-or-publish-docs:
+    name: Preview or publish docs
     needs: changed-files
     if: |
-      github.ref == 'refs/heads/main' &&
+      github.ref_type != 'tag' &&
       (needs.changed-files.outputs.docs == 'true' || github.event_name == 'workflow_dispatch') &&
       (github.event.inputs.tag == '' || github.event.inputs.tag == null)
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout main branch
+      - name: Determine context
+        id: ctx
+        run: |
+          if [ "$GITHUB_REF" = "refs/heads/main" ]; then
+            echo "is_main=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_main=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Checkout source branch
         uses: actions/checkout@v4
         with:
-          ref: main
-          path: main-checkout
+          path: source-checkout
           fetch-depth: 1
 
       - name: Checkout docs-website branch
@@ -164,54 +176,47 @@ jobs:
           path: docs-checkout
           fetch-depth: 1
           token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Setup Git
-        run: |
-          cd docs-checkout
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
       - name: Sync dev content from main
         run: |
           # Sync pages/ directory (dev content)
-          echo "Syncing pages/ from main to docs-website branch..."
+          echo "Syncing pages/ to docs-website branch..."
           rm -rf docs-checkout/fern/pages
-          cp -r main-checkout/docs/pages docs-checkout/fern/pages
+          cp -r source-checkout/docs/pages docs-checkout/fern/pages
 
           # Sync versions/dev.yml (dev navigation)
-          echo "Syncing versions/dev.yml from main to docs-website branch..."
-          cp main-checkout/docs/versions/dev.yml docs-checkout/fern/versions/dev.yml
+          echo "Syncing versions/dev.yml to docs-website branch..."
+          cp source-checkout/docs/versions/dev.yml docs-checkout/fern/versions/dev.yml
 
           # Sync assets/ directory
-          echo "Syncing assets/ from main to docs-website branch..."
+          echo "Syncing assets/ to docs-website branch..."
           rm -rf docs-checkout/fern/assets
-          cp -r main-checkout/docs/assets docs-checkout/fern/assets
+          cp -r source-checkout/docs/assets docs-checkout/fern/assets
 
           # Sync fern.config.json
-          echo "Syncing fern.config.json from main to docs-website branch..."
-          cp main-checkout/docs/fern.config.json docs-checkout/fern/fern.config.json
+          echo "Syncing fern.config.json to docs-website branch..."
+          cp source-checkout/docs/fern.config.json docs-checkout/fern/fern.config.json
 
           # Sync .gitignore if it exists
-          if [ -f main-checkout/docs/.gitignore ]; then
-            cp main-checkout/docs/.gitignore docs-checkout/fern/.gitignore
+          if [ -f source-checkout/docs/.gitignore ]; then
+            cp source-checkout/docs/.gitignore docs-checkout/fern/.gitignore
           fi
 
           # Sync convert_callouts.py script
-          if [ -f main-checkout/docs/convert_callouts.py ]; then
-            cp main-checkout/docs/convert_callouts.py docs-checkout/fern/convert_callouts.py
+          if [ -f source-checkout/docs/convert_callouts.py ]; then
+            cp source-checkout/docs/convert_callouts.py docs-checkout/fern/convert_callouts.py
           fi
 
           # Sync components/ directory (e.g., CustomFooter.tsx)
-          if [ -d main-checkout/docs/components ]; then
-            echo "Syncing components/ from main to docs-website branch..."
+          if [ -d source-checkout/docs/components ]; then
+            echo "Syncing components/ to docs-website branch..."
             rm -rf docs-checkout/fern/components
-            cp -r main-checkout/docs/components docs-checkout/fern/components
+            cp -r source-checkout/docs/components docs-checkout/fern/components
           fi
 
           # Sync main.css
-          if [ -f main-checkout/docs/main.css ]; then
-            echo "Syncing main.css from main to docs-website branch..."
-            cp main-checkout/docs/main.css docs-checkout/fern/main.css
+          if [ -f source-checkout/docs/main.css ]; then
+            echo "Syncing main.css to docs-website branch..."
+            cp source-checkout/docs/main.css docs-checkout/fern/main.css
           fi
 
       - name: Convert GitHub callouts to Fern format
@@ -230,8 +235,8 @@ jobs:
           echo "Preserved products[0] block:"
           cat /tmp/preserved_product.yml
 
-          # Copy docs.yml from main to get config updates (redirects, layout, etc.)
-          cp ../../main-checkout/docs/docs.yml docs.yml
+          # Copy docs.yml from source to get config updates (redirects, layout, etc.)
+          cp ../../source-checkout/docs/docs.yml docs.yml
 
           # Restore the preserved products[0] block
           yq -i '.products[0] = load("/tmp/preserved_product.yml")' docs.yml
@@ -252,8 +257,61 @@ jobs:
             git status --short
           fi
 
-      - name: Commit and push changes
+      - name: Setup Node.js
+        if: steps.changes.outputs.has_changes == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install Fern CLI
         if: steps.changes.outputs.has_changes == 'true'
+        run: npm install -g fern-api
+
+      ##########################################################################
+      # PREVIEW - Generate a preview URL for docs changes
+      ##########################################################################
+
+      - name: Generate docs preview
+        if: steps.ctx.outputs.is_main != 'true' && steps.changes.outputs.has_changes == 'true'
+        id: preview
+        working-directory: docs-checkout/fern
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+        run: |
+          OUTPUT=$(fern generate --docs --preview 2>&1)
+          FERN_EXIT=$?
+          echo "$OUTPUT"
+          if [ $FERN_EXIT -ne 0 ]; then
+            echo "::warning::Fern docs preview generation failed (exit $FERN_EXIT)"
+          fi
+          URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K\S+') || true
+          if [ -n "$URL" ]; then
+            echo "url=$URL" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Comment preview URL on PR
+        if: steps.ctx.outputs.is_main != 'true' && steps.preview.outputs.url != '' && startsWith(github.ref, 'refs/heads/pull-request/')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PR_NUM="${GITHUB_REF##*/}"
+          gh pr comment "https://github.com/${{ github.repository }}/pull/${PR_NUM}" \
+            --edit-last --create-if-none \
+            --body "🌿 **Fern Docs Preview:** ${{ steps.preview.outputs.url }}/dev"
+
+      ##########################################################################
+      # PUSH AND PUBLISH - push changes to docs-website branch and publish docs
+      ##########################################################################
+
+      - name: Setup Git
+        if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
+        run: |
+          cd docs-checkout
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Commit and push changes
+        if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
         run: |
           cd docs-checkout
 
@@ -269,18 +327,8 @@ jobs:
 
           echo "Successfully synced dev docs to docs-website branch"
 
-      - name: Setup Node.js
-        if: steps.changes.outputs.has_changes == 'true'
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install Fern CLI
-        if: steps.changes.outputs.has_changes == 'true'
-        run: npm install -g fern-api
-
       - name: Publish Docs
-        if: steps.changes.outputs.has_changes == 'true'
+        if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
         env:
           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
         working-directory: docs-checkout/fern
@@ -472,7 +520,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install Fern CLI
         run: npm install -g fern-api