Add documentation preview workflow for PRs changing .po files

Author: sepehr-rs

.github/workflows/build-and-deploy.yml

@@ -2,16 +2,14 @@ name: Build and Deploy to GitHub Pages
 
 on:
   schedule:
-    - cron: '0 2 * * *' 
+    - cron: '0 2 * * *'
   push:
     branches:
       - 3.14
   workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
 concurrency:
   group: "pages"
@@ -26,16 +24,16 @@ jobs:
         with:
           repository: python/cpython
           ref: v3.14.6
-          
+
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: '3.12'
-          
+
       - name: Setup virtual environment
         run: make venv
         working-directory: ./Doc
-        
+
       - name: Checkout translation files
         uses: actions/checkout@v4
         with:
@@ -52,26 +50,15 @@ jobs:
 
       - name: Setup problem matcher
         uses: sphinx-doc/github-problem-matcher@v1.1
-        
+
       - name: Build documentation
         run: make -e SPHINXOPTS="--color -D language='fa' -D gettext_allow_fuzzy_translations=1 --keep-going" html
         working-directory: ./Doc
-        
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
-        
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: Doc/build/html
 
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: Doc/build/html
+          keep_files: true
+          enable_jekyll: false

.github/workflows/build-docs-workflow.yml .github/workflows/build-docs-preview.yml.github/workflows/build-docs-workflow.yml renamed to .github/workflows/build-docs-preview.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Checkout translation files (this PR's branch)
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.pull_request.head.sha }}  # <-- the PR's actual commit
+          ref: ${{ github.event.pull_request.head.sha }}
           path: Doc/locales/fa/LC_MESSAGES
 
       - name: Install gettext
@@ -48,6 +48,22 @@ jobs:
           echo "exit_code=${PIPESTATUS[0]}" >> $GITHUB_OUTPUT
         working-directory: ./Doc
 
+      - name: Patch HTML static paths
+        # Sphinx builds _static paths as relative (e.g. ../../_static/),
+        # which breaks when served from a subdirectory like /previews/12/.
+        # We rewrite them to absolute URLs so CSS/JS load correctly
+        # regardless of which subdirectory the HTML file is in.
+        run: |
+          BASE="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/${{ github.event.pull_request.number }}"
+          find Doc/build/html -name "*.html" | while read f; do
+            sed -i 's|<base href="[^"]*">||g' "$f"
+            sed -i "s|href=\"\(\.\./\)*_static/|href=\"$BASE/_static/|g" "$f"
+            sed -i "s|src=\"\(\.\./\)*_static/|src=\"$BASE/_static/|g" "$f"
+          done
+
+      - name: Move log to root
+        run: mv Doc/build.log build.log
+
       - name: Save PR number
         run: echo "${{ github.event.pull_request.number }}" > pr_number.txt
 
@@ -57,4 +73,11 @@ jobs:
           name: build-result
           path: |
             build.log
-            pr_number.txt
+            pr_number.txt
+
+      - name: Upload HTML preview
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: Doc/build/html/
+          retention-days: 7

.github/workflows/comment-docs-preview.yml

@@ -6,23 +6,58 @@ on:
     workflows: ["Build Docs Preview"]
     types:
       - completed
+  pull_request:
+    types:
+      - closed
+    paths:
+      - '**/*.po'
 
 jobs:
   comment:
+    if: github.event_name == 'workflow_run'
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
+      contents: write
+      actions: read
 
     steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure gh-pages branch exists
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if ! git ls-remote --exit-code --heads origin gh-pages; then
+            echo "gh-pages branch not found, creating it..."
+            git checkout --orphan gh-pages
+            git rm -rf .
+            echo "# Doc Previews" > README.md
+            git add README.md
+            git commit -m "chore: initialize gh-pages branch"
+            git push origin gh-pages
+            git checkout -
+          else
+            echo "gh-pages branch already exists, skipping."
+          fi
+
       - name: Download build result
         uses: actions/download-artifact@v4
         with:
           name: build-result
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
 
-      - name: Debug artifact contents       # <-- add this temporarily
-        run: find . -type f | head -30
+      - name: Download HTML preview
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: html-preview/
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
 
       - name: Read PR number
         id: pr
@@ -31,23 +66,36 @@ jobs:
       - name: Read build log
         id: log
         run: |
-          # Grab the last 20 lines so the comment isn't massive
-          LOG=$(tail -20 build.log)
-          # GitHub Actions has a specific way to handle multiline strings
+          LOG=$(find . -name "build.log" | head -1 | xargs tail -20)
           echo "content<<EOF" >> $GITHUB_OUTPUT
           echo "$LOG" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
 
+      - name: Deploy preview to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./html-preview
+          destination_dir: previews/${{ steps.pr.outputs.number }}
+          keep_files: true
+          enable_jekyll: false
+
       - name: Post comment
         uses: actions/github-script@v7
         with:
           script: |
             const success = '${{ github.event.workflow_run.conclusion }}' === 'success';
             const icon = success ? '✅' : '❌';
             const status = success ? 'succeeded' : 'failed';
+            const prNumber = ${{ steps.pr.outputs.number }};
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const previewUrl = `https://${owner}.github.io/${repo}/previews/${prNumber}/index.html`;
 
             const body = `### ${icon} Docs build ${status}
 
+            ${success ? `📖 **[Preview the docs](${previewUrl})**` : ''}
+
             <details>
             <summary>Build log (last 20 lines)</summary>
 
@@ -58,8 +106,44 @@ jobs:
             </details>`;
 
             github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: ${{ steps.pr.outputs.number }},
-              body: body
-            });
+              owner,
+              repo,
+              issue_number: prNumber,
+              body
+            });
+
+  cleanup:
+    if: github.event_name == 'pull_request' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check if gh-pages exists
+        id: check
+        run: |
+          if git ls-remote --exit-code --heads https://github.com/${{ github.repository }}.git gh-pages; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Checkout gh-pages
+        if: steps.check.outputs.exists == 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+
+      - name: Remove preview folder
+        if: steps.check.outputs.exists == 'true'
+        run: |
+          PR=${{ github.event.pull_request.number }}
+          if [ -d "previews/$PR" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git rm -rf "previews/$PR"
+            git commit -m "chore: remove preview for PR #$PR"
+            git push
+          else
+            echo "No preview folder found for PR #$PR, nothing to clean up."
+          fi

.github/workflows/sync-with-cpython.yml

@@ -70,7 +70,7 @@ jobs:
             rel="${f#.pot-templates/}"
             po="${rel%.pot}.po"
             if [ -f "$po" ]; then
-              msgmerge --update --backup=off --no-location "$po" "$f"
+              msgmerge --update --backup=off --no-location --no-wrap "$po" "$f"
             fi
           done
 
@@ -149,16 +149,31 @@ jobs:
       - name: Clean up scratch files
         run: rm -rf .cpython-src .pot-templates
 
+      - name: Stage changes
+        run: git add --all
+
+      - name: Unstage POT-Creation-Date-only changes
+        run: |
+          git diff --staged --name-only | while read f; do
+            if git diff --staged -U0 -- "$f" \
+                | grep '^[+-]' \
+                | grep -v '^[+-][+-][+-]' \
+                | grep -qv 'POT-Creation-Date'; then
+              : # has real changes, keep staged
+            else
+              git restore --staged "$f"
+              git restore "$f"
+            fi
+          done
+
       - name: Commit if changed
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add --all
-          git diff --staged -U0 \
-            | grep '^[+-]' \
-            | grep -v '^[+-][+-][+-]' \
-            | grep -qv 'POT-Creation-Date' \
-            || { echo "Only POT-Creation-Date changed, skipping commit."; exit 0; }
+          if git diff --staged --quiet; then
+            echo "Nothing to commit, skipping."
+            exit 0
+          fi
           git commit -m \
             "chore: sync msgids with CPython ${{ github.event.inputs.cpython_tag || 'v3.14.6' }}"
           git push