Enhance publish-docs workflow: Include triggering upstream PR details in autogenerated docs PRs

.github/workflows/publish-docs.yaml

@@ -146,6 +146,87 @@ jobs:
           cd docs
           git status --porcelain -unormal -- *.md
 
+      # Prepare PR context information based on trigger type
+      # This step captures details about what triggered the workflow and formats them
+      # into a meaningful PR title and body for the auto-generated docs PR.
+      #
+      # Scenarios handled:
+      # 1. Push events from merged PRs (detected by "(#123)" pattern in commit message)
+      #    - Extracts PR number and title from the commit message
+      #    - Creates a link back to the original PR
+      # 2. Push events from direct commits (no PR pattern in message)
+      #    - Includes branch name, commit SHA, author, and commit message
+      # 3. Manual workflow_dispatch events
+      #    - Includes who triggered it and the current branch/commit
+      - name: Prepare PR context
+        id: pr-context
+        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.open_pull_request == 'true')
+        run: |
+          # Change to radius directory to extract commit information
+          # Note: ${{ github.sha }} refers to the triggering commit in the radius repository
+          cd radius
+
+          # Extract commit information
+          COMMIT_MESSAGE=$(git log -1 --pretty=format:"%s" ${{ github.sha }})
+          COMMIT_AUTHOR=$(git log -1 --pretty=format:"%an" ${{ github.sha }})
+
+          # Determine the source of this workflow run
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            # Triggered by a push to main or release branch
+            # Check if this is a merge commit from a PR
+            # GitHub's squash merge format: "Title (#123)" - PR number at end of message
+            # This pattern specifically targets squash merges, which is the default for this repo
+            if [[ "$COMMIT_MESSAGE" =~ \(#([0-9]+)\)$ ]]; then
+              # Extract PR number from commit message
+              PR_NUMBER="${BASH_REMATCH[1]}"
+
+              # For merged PRs, try to get the PR title (everything before " (#123)")
+              PR_TITLE="${COMMIT_MESSAGE% (#$PR_NUMBER)}"
+
+              echo "pr-title=Update auto-generated documentation (PR #$PR_NUMBER)" >> $GITHUB_OUTPUT
+              echo "pr-body<<EOF" >> $GITHUB_OUTPUT
+              echo "## Autogenerated PR" >> $GITHUB_OUTPUT
+              echo "" >> $GITHUB_OUTPUT
+              echo "This PR updates the auto-generated reference documentation." >> $GITHUB_OUTPUT
+              echo "" >> $GITHUB_OUTPUT
+              echo "### Triggered by" >> $GITHUB_OUTPUT
+              echo "**Pull Request:** [#$PR_NUMBER - $PR_TITLE](https://github.com/${{ github.repository }}/pull/$PR_NUMBER)" >> $GITHUB_OUTPUT
+              echo "**Branch:** \`${GITHUB_REF##*/}\`" >> $GITHUB_OUTPUT
+              echo "**Commit:** [\`${{ github.sha }}\`](https://github.com/${{ github.repository }}/commit/${{ github.sha }})" >> $GITHUB_OUTPUT
+              echo "**Author:** $COMMIT_AUTHOR" >> $GITHUB_OUTPUT
+              echo "EOF" >> $GITHUB_OUTPUT
+            else
+              # Regular push commit (not from a PR merge)
+              echo "pr-title=Update auto-generated documentation (${GITHUB_REF##*/})" >> $GITHUB_OUTPUT
+              echo "pr-body<<EOF" >> $GITHUB_OUTPUT
+              echo "## Autogenerated PR" >> $GITHUB_OUTPUT
+              echo "" >> $GITHUB_OUTPUT
+              echo "This PR updates the auto-generated reference documentation." >> $GITHUB_OUTPUT
+              echo "" >> $GITHUB_OUTPUT
+              echo "### Triggered by" >> $GITHUB_OUTPUT
+              echo "**Branch:** \`${GITHUB_REF##*/}\`" >> $GITHUB_OUTPUT
+              echo "**Commit:** [\`${{ github.sha }}\`](https://github.com/${{ github.repository }}/commit/${{ github.sha }})" >> $GITHUB_OUTPUT
+              echo "**Author:** $COMMIT_AUTHOR" >> $GITHUB_OUTPUT
+              echo "**Message:** $COMMIT_MESSAGE" >> $GITHUB_OUTPUT
+              echo "EOF" >> $GITHUB_OUTPUT
+            fi
+          else
+            # Triggered by workflow_dispatch
+            echo "pr-title=Update auto-generated documentation (manual trigger)" >> $GITHUB_OUTPUT
+            echo "pr-body<<EOF" >> $GITHUB_OUTPUT
+            echo "## Autogenerated PR" >> $GITHUB_OUTPUT
+            echo "" >> $GITHUB_OUTPUT
+            echo "This PR updates the auto-generated reference documentation." >> $GITHUB_OUTPUT
+            echo "" >> $GITHUB_OUTPUT
+            echo "### Triggered by" >> $GITHUB_OUTPUT
+            echo "**Trigger:** Manual workflow dispatch" >> $GITHUB_OUTPUT
+            echo "**Triggered by:** @${{ github.actor }}" >> $GITHUB_OUTPUT
+            echo "**Branch:** \`${GITHUB_REF##*/}\`" >> $GITHUB_OUTPUT
+            echo "**Commit:** [\`${{ github.sha }}\`](https://github.com/${{ github.repository }}/commit/${{ github.sha }})" >> $GITHUB_OUTPUT
+            echo "**Commit Message:** $COMMIT_MESSAGE" >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+          fi
+
       - name: Create pull request
         if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.open_pull_request == 'true')
         uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
@@ -159,13 +240,7 @@ jobs:
           signoff: true
           branch: reference-cli/patch-${{ github.sha }}
           delete-branch: true
-          title: |
-            Update auto-generated documentation
-          body: |
-            ## Autogenerated PR
-
-            This PR updates the auto-generated reference documentation.
-
-            GitHub SHA: ${{ github.sha }}
+          title: ${{ steps.pr-context.outputs.pr-title }}
+          body: ${{ steps.pr-context.outputs.pr-body }}
           commit-message: |
             Autogenerate reference docs