From ab3354285a00e6102d45e0cb0405952b1b812da1 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Fri, 6 Sep 2024 10:32:03 +0900
Subject: [PATCH 1/4] Use artifact-doc-develop for PR event

---
 .ci/create-changes-html.sh                    |  6 ++
 .github/workflows/doc-build.yml               | 78 +++++++++++++------
 src/sage/crypto/sbox.pyx                      |  2 +-
 src/sage/matrix/matrix2.pyx                   |  2 +-
 .../rings/polynomial/polynomial_element.pyx   |  4 +-
 src/sage/rings/ring_extension.pyx             |  2 +-
 src/sage/rings/ring_extension_element.pyx     |  2 +-
 7 files changed, 66 insertions(+), 30 deletions(-)

diff --git a/.ci/create-changes-html.sh b/.ci/create-changes-html.sh
index 0e80d0d2814..0cc86f34b13 100755
--- a/.ci/create-changes-html.sh
+++ b/.ci/create-changes-html.sh
@@ -16,6 +16,12 @@ echo '<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highli
 echo '<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>' >> CHANGES.html
 echo '<script>hljs.highlightAll();</script>' >> CHANGES.html
 cat >> CHANGES.html << EOF
+<style>
+  p.diff a:first-child {
+    font-weight: bold;
+    font-size: x-large;
+  }
+</style>
 <script>
 document.addEventListener('DOMContentLoaded', () => {
 // This URL is hardcoded in the file .github/workflows/doc-publish.yml.
diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 9deab60f8be..247db09eafc 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -114,7 +114,6 @@ jobs:
       - name: Start container
         id: container
         # Try to continue when "exporting to GitHub Actions Cache" failed with timeout
-        if: (success() || failure())
         run: |
           docker run --name BUILD -dit \
                      --mount type=bind,src=$(pwd),dst=$(pwd) \
@@ -122,32 +121,50 @@ jobs:
                      ${{ env.BUILD_IMAGE }} /bin/sh
 
       #
-      # On PRs and pushes to develop
+      # On pull request and push to develop events
       #
 
+      - name: Get workflow run-id
+        id: get_run_id
+        if: steps.container.outcome == 'success' && !startsWith(github.ref, 'refs/tags/') && github.event_name == 'pull_request'
+        run: |
+          RESPONSE=$(curl -s -L \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+            "https://api.github.com/repos/${{ github.repository }}/actions/runs?event=push&branch=develop&status=completed")
+          RUN_ID=$(echo "$RESPONSE" | jq -r --arg name "${{ github.workflow }}" --arg conclusion "success" \
+            '.workflow_runs[] | select(.name == $name and .conclusion == $conclusion) | .id' | head -n 1)
+          echo "RUN_ID=$RUN_ID" >> $GITHUB_ENV
+
+      - name: Download old doc
+        id: download-doc
+        if: steps.get_run_id.outcome == 'success'
+        uses: actions/download-artifact@v4
+        with:
+          name: doc-develop
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          run-id: ${{ env.RUN_ID }}
+
       - name: Store old doc
         id: worktree
-        if: (success() || failure()) && steps.container.outcome == 'success' && !startsWith(github.ref, 'refs/tags/')
+        if: steps.download-doc.outcome == 'success'
         run: |
           git config --global --add safe.directory $(pwd)
           git config --global user.email "ci-sage@example.com"
           git config --global user.name "Build documentation workflow"
-          mkdir -p doc
-          # Check if we are on PR
+          unzip doc.zip
           PR_NUMBER=""
-          if [[ -n "$GITHUB_REF" ]]; then
-            if [[ "$GITHUB_REF" =~ refs/pull/([0-9]+)/merge ]]; then
-              PR_NUMBER="${BASH_REMATCH[1]}"
-            fi
+          if [[ "$GITHUB_REF" =~ refs/pull/([0-9]+)/merge ]]; then
+            PR_NUMBER="${BASH_REMATCH[1]}"
           fi
-          # If so, then prepare to create CHANGES.html
+          # Create CHANGES.html
           if [[ -n "$PR_NUMBER" ]]; then
             # mathjax path in old doc (regex)
             mathjax_path_from="[-./A-Za-z_]*/tex-chtml[.]js?v=[0-9a-f]*"
             # mathjax path in new doc
             mathjax_path_to=$(docker exec -e SAGE_USE_CDNS=yes BUILD /sage/sage -python -c "from sage_docbuild.conf import mathjax_path; print(mathjax_path)")
             new_version=$(docker exec BUILD cat src/VERSION.txt)
-            docker cp BUILD:/sage/local/share/doc/sage/html doc/
             # Wipe out chronic diffs between old doc and new doc
             (cd doc && \
              find . -name "*.html" | xargs sed -i -e '/class="sidebar-brand-text"/ s/Sage [0-9a-z.]* /Sage '"$new_version"' /' \
@@ -159,14 +176,14 @@ jobs:
             # Create git repo from old doc
             (cd doc && \
              git init && \
-             (echo "*.svg binary"; echo "*.pdf binary") >> .gitattributes && \
-             (echo ".buildinfo"; echo '*.inv'; echo '.git*'; echo '*.svg'; echo '*.pdf'; echo '*.png'; echo 'searchindex.js') > .gitignore; \
+             (echo "*.svg binary"; echo "*.pdf binary") > .gitattributes && \
+             (echo ".buildinfo"; echo '*.inv'; echo '.git*'; echo '*.svg'; echo '*.pdf'; echo '*.png'; echo 'searchindex.js') > .gitignore && \
              git add -A && git commit --quiet -m 'old')
           fi
 
       - name: Build doc
         id: docbuild
-        if: (success() || failure()) && steps.worktree.outcome == 'success' && !startsWith(github.ref, 'refs/tags/')
+        if: steps.container.outcome == 'success' && !startsWith(github.ref, 'refs/tags/')
         # Always non-incremental because of the concern that
         # incremental docbuild may introduce broken links (inter-file references) though build succeeds
         run: |
@@ -175,18 +192,22 @@ jobs:
           export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
           make doc-clean doc-uninstall
           export SAGE_USE_CDNS=yes
+          export SAGE_DOCBUILD_OPTS="--include-tests-blocks"
           ./config.status && make sagemath_doc_html-no-deps
         shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
       - name: Copy doc
         id: copy
-        if: (success() || failure()) && steps.docbuild.outcome == 'success'
+        if: steps.docbuild.outcome == 'success'
         run: |
           set -ex
-          # We copy everything to a local folder
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/html doc
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html doc
-          # Check if we are on PR
+          # Simpler "docker cp --follow-link ... doc" does not work
+          mkdir -p doc
+          mkdir -p temp
+          docker cp --follow-link BUILD:/sage/local/share/doc/sage/html temp
+          docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html temp
+          cp -r -L temp/* doc/
+          # Check if we are on pull request event
           PR_NUMBER=""
           if [[ -n "$GITHUB_REF" ]]; then
             if [[ "$GITHUB_REF" =~ refs/pull/([0-9]+)/merge ]]; then
@@ -221,19 +242,28 @@ jobs:
 
       - name: Upload doc
         id: upload
-        if: (success() || failure()) && steps.copy.outcome == 'success'
+        if: steps.copy.outcome == 'success'
         uses: actions/upload-artifact@v4
         with:
           name: doc
           path: doc.zip
 
+      - name: Upload doc-develop
+        # artifact doc-develop is used for doc build on pull request event
+        id: upload-push
+        if: steps.copy.outcome == 'success' && github.event_name == 'push'
+        uses: actions/upload-artifact@v4
+        with:
+          name: doc-${{ github.ref_name }}
+          path: doc.zip
+
       #
-      # On release tags: live doc and wheels
+      # On release tag event
       #
 
       - name: Build live doc
         id: buildlivedoc
-        if: (success() || failure()) && startsWith(github.ref, 'refs/tags/')
+        if: startsWith(github.ref, 'refs/tags/')
         run: |
           export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
           export PATH="build/bin:$PATH"
@@ -249,7 +279,7 @@ jobs:
 
       - name: Copy live doc
         id: copylivedoc
-        if: (success() || failure()) && steps.buildlivedoc.outcome == 'success'
+        if: steps.buildlivedoc.outcome == 'success'
         run: |
           mkdir -p ./livedoc
           # We copy everything to a local folder
@@ -259,7 +289,7 @@ jobs:
           zip -r livedoc.zip livedoc
 
       - name: Upload live doc
-        if: (success() || failure()) && steps.copylivedoc.outcome == 'success'
+        if: steps.copylivedoc.outcome == 'success'
         uses: actions/upload-artifact@v4
         with:
           name: livedoc
diff --git a/src/sage/crypto/sbox.pyx b/src/sage/crypto/sbox.pyx
index 30b7a3cd8c9..af8638ea8e3 100644
--- a/src/sage/crypto/sbox.pyx
+++ b/src/sage/crypto/sbox.pyx
@@ -645,7 +645,7 @@ cdef class SBox(SageObject):
             [0 0 2 0 0 0 0 0 0 0 0 0 0 0 0 2]
             [0 2 0 0 0 0 0 0 0 0 0 0 2 0 0 0]
 
-        TESTS::
+        TESTS:
 
         Testing square SBoxes::
 
diff --git a/src/sage/matrix/matrix2.pyx b/src/sage/matrix/matrix2.pyx
index 3682c2be14e..d2f0815e81e 100644
--- a/src/sage/matrix/matrix2.pyx
+++ b/src/sage/matrix/matrix2.pyx
@@ -7938,7 +7938,7 @@ cdef class Matrix(Matrix1):
             sage: m == transformation_matrix * m_original
             True
 
-        TESTS::
+        TESTS:
 
         Check that :issue:`34724` is fixed (indirect doctest)::
 
diff --git a/src/sage/rings/polynomial/polynomial_element.pyx b/src/sage/rings/polynomial/polynomial_element.pyx
index 7c1ca199ced..d60c0c752d6 100644
--- a/src/sage/rings/polynomial/polynomial_element.pyx
+++ b/src/sage/rings/polynomial/polynomial_element.pyx
@@ -4872,7 +4872,7 @@ cdef class Polynomial(CommutativePolynomial):
             -1 * 3^15 * 23 * 887 * 12583 * 6335047 * 371692813
 
         Factoring over a number field over which we cannot factor the
-        discriminant and over which `nffactor()` fails::
+        discriminant and over which ``nffactor()`` fails::
 
             sage: # needs sage.libs.pari sage.rings.number_field
             sage: p = next_prime(10^50); q = next_prime(10^51); n = p*q
@@ -4920,7 +4920,7 @@ cdef class Polynomial(CommutativePolynomial):
             sage: (x1 - x2).factor()                                                    # needs sage.libs.singular
             -x + x
 
-        Check that :issue:`26421' is fixed::
+        Check that :issue:`26421` is fixed::
 
             sage: R.<t> = LaurentPolynomialRing(ZZ)
             sage: P.<x> = R[]
diff --git a/src/sage/rings/ring_extension.pyx b/src/sage/rings/ring_extension.pyx
index 86ac9756351..9d8a626094a 100644
--- a/src/sage/rings/ring_extension.pyx
+++ b/src/sage/rings/ring_extension.pyx
@@ -1952,7 +1952,7 @@ cdef class RingExtension_generic(Parent):
 
         TESTS:
 
-            Ensure issue :issue:`34692` is fixed::
+        Ensure issue :issue:`34692` is fixed::
 
             sage: Fq = GF(11)
             sage: FqX.<X> = Fq[]
diff --git a/src/sage/rings/ring_extension_element.pyx b/src/sage/rings/ring_extension_element.pyx
index e3184503d77..4e3c50ef09d 100644
--- a/src/sage/rings/ring_extension_element.pyx
+++ b/src/sage/rings/ring_extension_element.pyx
@@ -329,7 +329,7 @@ cdef class RingExtensionElement(CommutativeAlgebraElement):
             sage: g.parent()
             Finite Field in z2 of size 5^2
 
-        TESTS::
+        TESTS:
 
         We check the case of a tower of extensions::
 

From 2c5d9c0b8fff3350651d10be8486c71e54dc16f9 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Fri, 6 Sep 2024 10:56:41 +0900
Subject: [PATCH 2/4] Remove spurious diffs in examples tabs

---
 .github/workflows/doc-build.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 247db09eafc..f0895778a17 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -172,6 +172,7 @@ jobs:
                                                   -e 's;'"$mathjax_path_from"';'"$mathjax_path_to"';' \
                                                   -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d' \
                                                   -e 's;#L[0-9]*";";' \
+                                                  -e 's;tab-set--[0-9]*-;tab-set-;' \
              && true)
             # Create git repo from old doc
             (cd doc && \
@@ -223,6 +224,7 @@ jobs:
                                                   -e '/<link rel="stylesheet"/ s/?v=[0-9a-f]*"/"/' \
                                                   -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d' \
                                                   -e 's;#L[0-9]*";";' \
+                                                  -e 's;tab-set--[0-9]*-;tab-set-;' \
              && git commit -a -m 'wipe-out')
             # Since HEAD is at commit 'wipe-out', HEAD~1 is commit 'new' (new doc), HEAD~2 is commit 'old' (old doc)
             (cd doc && git diff $(git rev-parse HEAD~2) -- "*.html") > diff.txt

From b9567a69abdc3364d1a84a5eebfeb398e2e0ec93 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Tue, 10 Sep 2024 14:36:33 +0900
Subject: [PATCH 3/4] Squeeze more disk space

---
 .github/workflows/doc-build.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index f0895778a17..7b4ea38e044 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -267,6 +267,8 @@ jobs:
         id: buildlivedoc
         if: startsWith(github.ref, 'refs/tags/')
         run: |
+          # Avoid running out of disk space
+          rm -rf upstream
           export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
           export PATH="build/bin:$PATH"
           eval $(sage-print-system-package-command auto update)

From 5e86fcdc39e56140174abe031de92ebf82abfa47 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Tue, 12 Nov 2024 08:06:22 +0900
Subject: [PATCH 4/4] Remove more spurious diffs

---
 .github/workflows/doc-build.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 7b4ea38e044..5eb5e932da9 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -168,7 +168,7 @@ jobs:
             # Wipe out chronic diffs between old doc and new doc
             (cd doc && \
              find . -name "*.html" | xargs sed -i -e '/class="sidebar-brand-text"/ s/Sage [0-9a-z.]* /Sage '"$new_version"' /' \
-                                                  -e '/<link rel="stylesheet"/ s/?v=[0-9a-f]*"/"/' \
+                                                  -e 's;?v=[0-9a-f]*";";' \
                                                   -e 's;'"$mathjax_path_from"';'"$mathjax_path_to"';' \
                                                   -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d' \
                                                   -e 's;#L[0-9]*";";' \
@@ -221,7 +221,7 @@ jobs:
             # Wipe out chronic diffs of new doc against old doc before creating CHANGES.html
             (cd doc && \
              find . -name "*.html" | xargs sed -i -e '/This is documentation/ s/ built with GitHub PR .* for development/ for development/' \
-                                                  -e '/<link rel="stylesheet"/ s/?v=[0-9a-f]*"/"/' \
+                                                  -e 's;?v=[0-9a-f]*";";' \
                                                   -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d' \
                                                   -e 's;#L[0-9]*";";' \
                                                   -e 's;tab-set--[0-9]*-;tab-set-;' \