docs: Add GitHub Pages deployment to dynamo.github.io for release branches (#1542)

Signed-off-by: Meenakshi Sharma <163925564+nvda-mesharma@users.noreply.github.com>

Author: nvda-mesharma

.github/workflows/generate-docs.yml

@@ -63,7 +63,19 @@ jobs:
     needs: build-docs
     runs-on: ubuntu-latest
 
-    if: startsWith(github.ref, 'refs/heads/release')
+    # Deploy on PRs targeting release branches
+    if: github.event_name == 'pull_request' && startsWith(github.base_ref, 'release')
+
+    # Prevent multiple deployments from running simultaneously
+    concurrency:
+      group: deploy-docs-${{ github.base_ref }}
+      cancel-in-progress: false
+
+    env:
+      DOCS_BASE_URL: "https://crispy-winner-3jnj38w.pages.github.io"
+      DOCS_REPOSITORY: "ai-dynamo/dynamo-docs"
+      DOCS_BRANCH: "main"
+      DOCS_ARTIFACT_NAME: "dynamo-docs"
 
     steps:
       - name: Checkout source repo
@@ -72,22 +84,78 @@ jobs:
       - name: Download documentation artifact
         uses: actions/download-artifact@v4
         with:
-          name: dynamo-docs-${{ github.run_id }}
-          path: dynamo-docs
+          name: ${{ env.DOCS_ARTIFACT_NAME }}-${{ github.run_id }}
+          path: ${{ env.DOCS_ARTIFACT_NAME }}
 
-      - name: Clean potentially stale metadata files
+      - name: Clean potentially stale metadata files (but preserve index)
         run: |
-          rm -f ./dynamo-docs/CNAME
-          rm -f ./dynamo-docs/_config.yml
-          rm -f ./dynamo-docs/index.html || true
+          rm -f ./${{ env.DOCS_ARTIFACT_NAME }}/CNAME
+          rm -f ./${{ env.DOCS_ARTIFACT_NAME }}/_config.yml
+          # Don't remove index.html - it's needed for navigation
+
+      - name: Determine deployment directory
+        id: deploy_dir
+        run: |
+          # For PRs, use consistent directory (latest commit overwrites previous)
+          SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-8)
+          echo "dir_name=${{ github.base_ref }}/pr-${{ github.event.number }}" >> $GITHUB_OUTPUT
+          echo "commit_ref=${{ github.sha }}" >> $GITHUB_OUTPUT
+          echo "short_sha=${SHORT_SHA}" >> $GITHUB_OUTPUT
 
       - name: Deploy to internal GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           personal_token: ${{ secrets.DOCS_TOKEN }}
-          external_repository: ai-dynamo/dynamo-docs
-          publish_branch: main
-          publish_dir: ./dynamo-docs
-          destination_dir: ${{ github.ref_name }}
-          commit_message: 'Deploy documentation from ${{ github.repository }}@${{ github.sha }} (branch: ${{ github.ref_name }})'
+          external_repository: ${{ env.DOCS_REPOSITORY }}
+          publish_branch: ${{ env.DOCS_BRANCH }}
+          publish_dir: ./${{ env.DOCS_ARTIFACT_NAME }}
+          destination_dir: ${{ steps.deploy_dir.outputs.dir_name }}
+          commit_message: 'Deploy documentation from ${{ github.repository }}@${{ steps.deploy_dir.outputs.commit_ref }} (branch: ${{ steps.deploy_dir.outputs.dir_name }})'
           keep_files: true
+
+      - name: Comment on PR with docs link
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const docsUrl = `${{ env.DOCS_BASE_URL }}/${{ steps.deploy_dir.outputs.dir_name }}/`;
+            const comment = `## 📚 Documentation Preview
+
+            **📖 View Latest Documentation:** [${docsUrl}](${docsUrl})
+            > **Latest Deployment:**
+            > - **Commit:** [\`${{ steps.deploy_dir.outputs.short_sha }}\`](https://github.com/${{ github.repository }}/commit/${{ github.sha }}) *(latest push)*
+            > - **Target:** \`${{ github.base_ref }}\`
+            > - **Updated:** ${new Date().toLocaleString('en-US', { timeZone: 'UTC', timeStyle: 'short', dateStyle: 'short' })} UTC
+            >
+            > **Note:** This link always shows the documentation for the latest commit. It may take a few minutes for GitHub Pages to update after each push.
+            ---
+
+            *Auto-updated by the documentation deployment workflow*`;
+
+            // Find and update existing comment, or create new one
+            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: comment
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: comment
+              });
+            }