ci : Add github action workflow to generate documentation preview (#2)

Add github action to generate documentation preview by publishing gh-pages on an external repository. This change adds four new github action workflows:
- Documentation Preview Request: A workflow that would run on the pull request and generate website and upload it as a github artifact.
- Documentation Preview Generator: A workflow that would get triggered on the completion of `Documentation Preview Request` workflow and it would download the uploaded artifact and deploy the content to github repository configured in secrets.
- Documentation Preview Cleanup Request: A workflow that would run on pull request upon the closing event of pull request. It would save pull request number as an artifact and upload it.
- Documentation Preview Cleanup: A workflow that would get triggered on the completion of `Documentation Preview Cleanup Request` workflow and it would download the uploaded artifact and update the github repository and remove the generated preview directory.

Signed-off-by: Rohan Kumar <[email protected]>

.github/workflows/documentation-preview-cleanup-request.yml

@@ -0,0 +1,22 @@
+name: Documentation Preview Cleanup Request
+
+on:
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  on-close:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Save the GH context in an artifact
+        env:
+          GH_CONTEXT: ${{ toJSON(github) }}
+        run: echo $GH_CONTEXT > github_context.json
+      - name: Upload the GH context artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-context
+          path: github_context.json
+

.github/workflows/documentation-preview-cleanup.yml

@@ -0,0 +1,41 @@
+name: Documentation Preview Cleanup
+
+on:
+  workflow_run:
+    workflows: [Documentation Preview Cleanup Request]
+    types:
+      - completed
+
+env:
+  PREVIEW_PUBLISH_USERNAME: ${{ secrets.PREVIEW_PUBLISH_USERNAME }}
+  PREVIEW_PUBLISH_REPOSITORY: ${{ secrets.PREVIEW_PUBLISH_REPOSITORY }}
+  PREVIEW_PUBLISH_BRANCH: ${{ secrets.PREVIEW_PUBLISH_BRANCH }}
+  PREVIEW_PUBLISH_TOKEN: ${{ secrets.PREVIEW_PUBLISH_TOKEN }}
+
+jobs:
+  on-close:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: cleanup-info
+          path: .
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Extract Pull Request ID from artifact
+        run: echo "PR_NUMBER=$(jq '.event.pull_request.number' github_context.json)" >> $GITHUB_ENV
+      - name: Push updates to external repository
+        run: |
+          git clone https://${PREVIEW_PUBLISH_USERNAME}:${PREVIEW_PUBLISH_TOKEN}@github.com/${PREVIEW_PUBLISH_USERNAME}/${PREVIEW_PUBLISH_REPOSITORY}.git -b ${PREVIEW_PUBLISH_BRANCH}
+          cd ${PREVIEW_PUBLISH_REPOSITORY}
+          rm -rf preview/pr/${PR_NUMBER}
+          git add preview/pr/${PR_NUMBER}
+          git commit -am "cleanup (preview) : remove preview for Pull Request #${PR_NUMBER}"
+          git push origin ${PREVIEW_PUBLISH_BRANCH}

.github/workflows/documentation-preview-request.yml

@@ -0,0 +1,30 @@
+name: Documentation Preview Request
+
+on:
+  pull_request: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: Build docs
+        run: CI=true make build_docs
+      - name: Check links in docs
+        run: make docs_check_links
+      - name: Create robots.txt
+        run: |
+          echo "User-agent: *" > ./public/robots.txt
+          echo "Disallow: /" >> ./public/robots.txt
+      - name: Save the GH context in an artifact
+        env:
+          GH_CONTEXT: ${{ toJSON(github) }}
+        run: echo $GH_CONTEXT > ./public/github_context.json
+      - name: Upload GitHub artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: public
+

.github/workflows/documentation-preview.yml

@@ -0,0 +1,49 @@
+name: Documentation Preview Generator
+
+on:
+  workflow_run:
+    workflows: [Documentation Preview Request]
+    types:
+      - completed
+
+env:
+  PREVIEW_PUBLISH_USERNAME: ${{ secrets.PREVIEW_PUBLISH_USERNAME }}
+  PREVIEW_PUBLISH_REPOSITORY: ${{ secrets.PREVIEW_PUBLISH_REPOSITORY }}
+  PREVIEW_PUBLISH_BRANCH: ${{ secrets.PREVIEW_PUBLISH_BRANCH }}
+  PREVIEW_PUBLISH_TOKEN: ${{ secrets.PREVIEW_PUBLISH_TOKEN }}
+
+jobs:
+  documentation-preview:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation
+          path: ./artifact
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+      - name: Extract Pull Request ID from artifact
+        run: |
+          echo "PR_NUMBER=$(jq '.event.pull_request.number' ./artifact/github_context.json)" >> $GITHUB_ENV
+          echo "PR_SHA=$(jq -r '.event.pull_request.head.sha' ./artifact/github_context.json | cut -c 1-7)" >> $GITHUB_ENV
+          rm ./artifact/github_context.json
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          personal_token: ${{ env.PREVIEW_PUBLISH_TOKEN }}
+          external_repository: ${{ env.PREVIEW_PUBLISH_USERNAME }}/${{ env.PREVIEW_PUBLISH_REPOSITORY }}
+          publish_dir: ./artifact
+          publish_branch: ${{ env.PREVIEW_PUBLISH_BRANCH }}
+          destination_dir: preview/pr/${{ env.PR_NUMBER }}/${{ env.PR_SHA}}
+          commit_message: "deploy documentation preview to GitHub Pages for PR #${{ env.PR_NUMBER }}"
+
+      - name: Comment PR with preview link
+        run: |
+          PREVIEW_URL="https://${PREVIEW_PUBLISH_USERNAME}.github.io/${PREVIEW_PUBLISH_REPOSITORY}/preview/pr/${PR_NUMBER}/${PR_SHA}/index.html"
+          curl -s --request POST \
+            --url "https://api.github.com/repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+            --header "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+            --header "Content-Type: application/json" \
+            --data "{\"body\":\"🚀 Documentation preview: ${PREVIEW_URL}\"}"