gh-38449: Include TESTS in doc preview for PRs

    
We include TESTS blocks in development documentation, so that they are
visible at least during development.

Then not to ruin CHANGES.html, we refactor doc build github workflow.
The idea is to upload artifact `doc-develop` so that doc diffs are
computed against the doc contained in the artifact.

test: https://doc-develop--sagemath-
test.netlify.app/html/en/reference/structure/sage/structure/sage_object
Look around  for new "TESTS" blocks.

We also remove all spurious diffs caused by EXAMPLES tabs indices
change. Tests for PR event:

doc-develop artifact:
https://github.com/kwankyu/sage/actions/runs/11787561475
doc-build workflow run:
https://github.com/kwankyu/sage/actions/runs/11789320959/job/32837887930

Note that doc build for this PR itself fails here, of course. We may
ignore this.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->

#38468
    
URL: #38449
Reported by: Kwankyu Lee
Reviewer(s): Dima Pasechnik

.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.

.github/workflows/doc-build.yml

@@ -114,59 +114,77 @@ 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) \
                      --workdir $(pwd) \
                      ${{ 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"' /' \
-                                                  -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]*";";' \
+                                                  -e 's;tab-set--[0-9]*-;tab-set-;' \
              && true)
             # 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 +193,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
@@ -199,9 +221,10 @@ 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-;' \
              && 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
@@ -221,20 +244,31 @@ 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: |
+          # 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)
@@ -249,7 +283,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 +293,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

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::
 

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)::
 

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[]

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[]

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::