From 02702c5bd3f480b9142f93d22550ede5e9517778 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Sun, 23 Jun 2024 22:14:34 +0900
Subject: [PATCH 01/10] Fix doc build for releases

---
 .ci/create-changes-html.sh          |  4 +-
 .github/workflows/doc-build-pdf.yml | 24 +++----
 .github/workflows/doc-build.yml     | 79 ++++++++++++-----------
 .github/workflows/doc-publish.yml   | 98 +++++++++++++----------------
 src/sage_docbuild/conf.py           |  8 ++-
 5 files changed, 107 insertions(+), 106 deletions(-)

diff --git a/.ci/create-changes-html.sh b/.ci/create-changes-html.sh
index 33fd9a52472..d061c725a68 100755
--- a/.ci/create-changes-html.sh
+++ b/.ci/create-changes-html.sh
@@ -19,7 +19,9 @@ echo '<script>hljs.highlightAll();</script>' >> CHANGES.html
 cat >> CHANGES.html << EOF
 <script>
 document.addEventListener('DOMContentLoaded', () => {
-const baseDocURL = 'https://sagemath.netlify.app'
+// This URL is hardcoded in the file .github/workflows/doc-publish.yml.
+// See NETLIFY_ALIAS of the "Deploy to Netlify" step.
+const baseDocURL = 'https://doc-develop--sagemath.netlify.app'
 const diffSite = 'https://pianomister.github.io/diffsite'
 const diffParagraphs = document.querySelectorAll('p.diff');
 diffParagraphs.forEach(paragraph => {
diff --git a/.github/workflows/doc-build-pdf.yml b/.github/workflows/doc-build-pdf.yml
index 2eac8e17ffc..b2de526ca94 100644
--- a/.github/workflows/doc-build-pdf.yml
+++ b/.github/workflows/doc-build-pdf.yml
@@ -30,7 +30,7 @@ env:
   EXTRA_CONFIGURE_ARGS:   --enable-fat-binary
 
 jobs:
-  build-docs-pdf:
+  build-doc-pdf:
     runs-on: ubuntu-latest
     services:
       # https://docs.docker.com/build/ci/github-actions/local-registry/
@@ -110,7 +110,9 @@ jobs:
                      --workdir $(pwd) \
                      ${{ env.BUILD_IMAGE }} /bin/sh
 
-      # Docs
+      #
+      # On PRs and pushes to branches
+      #
 
       - name: Update system packages
         id: packages
@@ -122,7 +124,7 @@ jobs:
           eval $(sage-print-system-package-command auto --spkg --yes --no-install-recommends install git texlive texlive_luatex free_fonts xindy)
         shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
-      - name: Build docs (PDF)
+      - name: Build doc (PDF)
         id: docbuild
         if: (success() || failure()) && steps.packages.outcome == 'success'
         run: |
@@ -130,21 +132,21 @@ jobs:
           make doc-clean doc-uninstall; make sagemath_doc_html-build-deps sagemath_doc_pdf-no-deps
         shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
-      - name: Copy docs
+      - name: Copy doc
         id: copy
         if: (success() || failure()) && steps.docbuild.outcome == 'success'
         run: |
           # For some reason the deploy step below cannot find /sage/...
           # So copy everything from there to local folder
-          mkdir -p ./docs
-          cp -r -L /sage/local/share/doc/sage/pdf ./docs
+          mkdir -p ./doc
+          cp -r -L /sage/local/share/doc/sage/pdf ./doc
           # Zip everything for increased performance
-          zip -r docs-pdf.zip docs
+          zip -r doc-pdf.zip doc
         shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
-      - name: Upload docs
+      - name: Upload doc
         if: (success() || failure()) && steps.copy.outcome == 'success'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: docs-pdf
-          path: docs-pdf.zip
+          name: doc-pdf
+          path: doc-pdf.zip
diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 01d05b25b5d..81e050df827 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -4,6 +4,14 @@ on:
   pull_request:
   merge_group:
   push:
+    tags:
+      # Match all release tags including beta, rc
+      - '[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.beta[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+.beta[0-9]+'
+      - '[0-9]+.[0-9]+.rc[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+.rc[0-9]+'
     branches:
       - master
       - develop
@@ -34,7 +42,7 @@ env:
   EXTRA_CONFIGURE_ARGS:   --enable-fat-binary
 
 jobs:
-  build-docs:
+  build-doc:
     runs-on: ubuntu-latest
     services:
       # https://docs.docker.com/build/ci/github-actions/local-registry/
@@ -114,11 +122,13 @@ jobs:
                      --workdir $(pwd) \
                      ${{ env.BUILD_IMAGE }} /bin/sh
 
-      # Docs
+      #
+      # On PRs and pushes to master or develop
+      #
 
-      - name: Store old docs
+      - name: Store old doc
         id: worktree
-        if: (success() || failure()) && steps.container.outcome == 'success'
+        if: (success() || failure()) && steps.container.outcome == 'success' && !startsWith(github.ref, 'refs/tags/')
         run: |
           git config --global --add safe.directory $(pwd)
           git config --global user.email "ci-sage@example.com"
@@ -128,24 +138,24 @@ jobs:
           # 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)
-          mkdir -p docs/
-          docker cp BUILD:/sage/local/share/doc/sage/html docs/
-          # Wipe out chronic diffs of old doc against new doc
-          (cd docs && \
+          mkdir -p doc/
+          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;'"$mathjax_path_from"';'"$mathjax_path_to"';' \
                                                 -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d')
           # Create git repo from old doc
-          (cd docs && \
+          (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; \
            git add -A && git commit --quiet -m "old")
 
-      - name: Build docs
+      - name: Build doc
         id: docbuild
-        if: (success() || failure()) && steps.worktree.outcome == 'success'
+        if: (success() || failure()) && steps.worktree.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: |
@@ -157,50 +167,43 @@ jobs:
           ./config.status && make sagemath_doc_html-no-deps
         shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
-      - name: Copy docs
+      - name: Copy doc
         id: copy
         if: (success() || failure()) && steps.docbuild.outcome == 'success'
         run: |
           set -ex
           # We copy everything to a local folder
-          docker cp BUILD:/sage/local/share/doc/sage/html docs
-          docker cp BUILD:/sage/local/share/doc/sage/index.html docs
-          (cd docs && git commit -a -m 'new')
+          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
+          (cd doc && git commit -a -m 'new')
           # Wipe out chronic diffs of new doc against old doc
-          (cd docs && \
+          (cd doc && \
            find . -name "*.html" | xargs sed -i -e '/This is documentation for/ s/ built with GitHub PR .*. Doc/. Doc/' \
                                                 -e '/<link rel="stylesheet"/ s/?v=[0-9a-f]*"/"/')
-          .ci/create-changes-html.sh $(cd docs && git rev-parse HEAD^) docs
+          .ci/create-changes-html.sh $(cd doc && git rev-parse HEAD^) doc
           # Restore the new doc from changes by "wipe out"
-          (cd docs && git checkout -f)
-          (cd docs && rm -rf .git)
-          mv CHANGES.html docs
-          # We also need to replace the symlinks because netlify is not following them
-          # CHECK IF STILL NEEDED
-          #cp -r -L $DOC_DIR ./docs
+          (cd doc && git checkout -f)
+          # Sometimes rm -rf .git errors out because of some diehard hidden files
+          (cd doc && rm -rf .git 2>/dev/null && rm .gitattributes 2>/dev/null)
+          mv CHANGES.html doc
           # Zip everything for increased performance
-          zip -r docs.zip docs
+          zip -r doc.zip doc
 
-      - name: Upload docs
+      - name: Upload doc
         id: upload
         if: (success() || failure()) && steps.copy.outcome == 'success'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: docs
-          path: docs.zip
+          name: doc
+          path: doc.zip
 
-      - name: Save space
-        id: savespace
-        if: (success() || failure()) && steps.upload.outcome == 'success' && github.repository == 'sagemath/sage' && github.ref == 'refs/heads/develop'
-        run: |
-          set -ex
-          # Save space on runner device before we start to build livedoc
-          rm -rf docs/
-          rm -f docs.zip
+      #
+      # On release tags: live doc and wheels
+      #
 
       - name: Build live doc
         id: buildlivedoc
-        if: (success() || failure()) && steps.savespace.outcome == 'success'
+        if: (success() || failure()) && startsWith(github.ref, 'refs/tags/')
         run: |
           export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
           export PATH="build/bin:$PATH"
@@ -227,7 +230,7 @@ jobs:
 
       - name: Upload live doc
         if: (success() || failure()) && steps.copylivedoc.outcome == 'success'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: livedoc
           path: livedoc.zip
diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
index bc12784cb9c..ee9de3c8c1c 100644
--- a/.github/workflows/doc-publish.yml
+++ b/.github/workflows/doc-publish.yml
@@ -14,9 +14,11 @@ permissions:
   pull-requests: write
 
 jobs:
-  upload-docs:
+  publish-doc:
     runs-on: ubuntu-latest
     if: github.event.workflow_run.conclusion == 'success'
+    env:
+      CAN_DEPLOY: ${{ secrets.NETLIFY_AUTH_TOKEN != '' &&  secrets.NETLIFY_SITE_ID != '' }}
     steps:
       - name: Get information about workflow origin
         uses: potiuk/get-workflow-origin@v1_5
@@ -24,44 +26,32 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           sourceRunId: ${{ github.event.workflow_run.id }}
+        if: env.CAN_DEPLOY == 'true'
 
-      # Once https://github.com/actions/download-artifact/issues/172 and/or https://github.com/actions/download-artifact/issues/60 is implemented, we can use the official download-artifact action
-      # For now use the solution from https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#using-data-from-the-triggering-workflow
-      - name: Download docs
-        uses: actions/github-script@v7.0.1
+      - name: Download doc
+        id: download-doc
+        uses: actions/download-artifact@v4
         with:
-          script: |
-            var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
-               owner: context.repo.owner,
-               repo: context.repo.repo,
-               run_id: ${{github.event.workflow_run.id }},
-            });
-            var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
-              return artifact.name == "docs"
-            })[0];
-            var download = await github.rest.actions.downloadArtifact({
-               owner: context.repo.owner,
-               repo: context.repo.repo,
-               artifact_id: matchArtifact.id,
-               archive_format: 'zip',
-            });
-            var fs = require('fs');
-            fs.writeFileSync('${{github.workspace}}/docs.zip', Buffer.from(download.data));
+          name: doc
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          run-id: ${{ github.event.workflow_run.id }}
+        if: steps.source-run-info.outputs.sourceEvent == 'pull_request' || (steps.source-run-info.outputs.sourceEvent == 'push' && steps.source-run-info.outputs.targetBranch == 'develop')
 
-      - name: Extract docs
-        run: unzip docs.zip -d docs && unzip docs/docs.zip -d docs/docs
+      - name: Extract doc
+        run: unzip doc.zip -d doc
+        if: steps.download-doc.outcome == 'success'
 
       - name: Deploy to Netlify
-        id: deploy-netlify
         uses: netlify/actions/cli@master
         with:
-          args: deploy --dir=docs/docs/docs ${NETLIFY_PRODUCTION:+"--prod"} --message ${NETLIFY_MESSAGE} --alias ${NETLIFY_ALIAS}
+          args: deploy --dir=doc/doc --message ${NETLIFY_MESSAGE} --alias ${NETLIFY_ALIAS}
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-          NETLIFY_PRODUCTION: ${{ github.ref == 'refs/heads/develop' }}
-          NETLIFY_MESSAGE: ${{ steps.source-run-info.outputs.pullRequestNumber }}
-          NETLIFY_ALIAS: preview-${{ steps.source-run-info.outputs.pullRequestNumber }}
+          NETLIFY_MESSAGE:  doc-${{ steps.source-run-info.outputs.pullRequestNumber && format('pr-{0}', steps.source-run-info.outputs.pullRequestNumber) || 'develop' }}
+          NETLIFY_ALIAS: doc-${{ steps.source-run-info.outputs.pullRequestNumber && format('pr-{0}', steps.source-run-info.outputs.pullRequestNumber) || 'develop' }}
+        if: steps.download-doc.outcome == 'success'
 
       # Add deployment as status check, PR comment and annotation
       # we could use the nwtgck/actions-netlify action for that, except for that it is not (yet) working in workflow_run context: https://github.com/nwtgck/actions-netlify/issues/545
@@ -74,6 +64,7 @@ jobs:
           message: |
             [Documentation preview for this PR](${{ steps.deploy-netlify.outputs.NETLIFY_URL }}/html/en) (built with commit ${{ steps.source-run-info.outputs.sourceHeadSha }}; [changes](${{ steps.deploy-netlify.outputs.NETLIFY_URL }}/CHANGES.html)) is ready! :tada:
             This preview will update shortly after each push to this PR.
+        if: steps.download-doc.outcome == 'success'
 
       - name: Update deployment status PR check
         uses: myrotvorets/set-commit-status-action@v2.0.1
@@ -95,43 +86,44 @@ jobs:
 
   publish-live-doc:
     runs-on: ubuntu-latest
-    if: github.event.workflow_run.conclusion == 'success' && github.repository == 'sagemath/sage' && github.event.workflow_run.head_branch == 'develop'
+    if: github.event.workflow_run.conclusion == 'success'
+    env:
+      CAN_DEPLOY: ${{ secrets.NETLIFY_AUTH_TOKEN != '' &&  secrets.NETLIFY_SITE_ID != '' }}
     steps:
+      - name: Get information about workflow origin
+        uses: potiuk/get-workflow-origin@v1_5
+        id: source-run-info
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          sourceRunId: ${{ github.event.workflow_run.id }}
+        if: env.CAN_DEPLOY == 'true'
+
       - name: Download live doc
-        uses: actions/github-script@v7.0.1
+        id: download-doc
+        uses: actions/download-artifact@v4
         with:
-          script: |
-            var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
-               owner: context.repo.owner,
-               repo: context.repo.repo,
-               run_id: ${{github.event.workflow_run.id }},
-            });
-            var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
-              return artifact.name == "livedoc"
-            })[0];
-            var download = await github.rest.actions.downloadArtifact({
-               owner: context.repo.owner,
-               repo: context.repo.repo,
-               artifact_id: matchArtifact.id,
-               archive_format: 'zip',
-            });
-            var fs = require('fs');
-            fs.writeFileSync('${{github.workspace}}/livedoc.zip', Buffer.from(download.data));
+          name: livedoc
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          run-id: ${{ github.event.workflow_run.id }}
+        if: steps.source-run-info.outputs.sourceEvent == 'push' && steps.source-run-info.outputs.targetBranch != 'develop'
 
       - name: Extract live doc
-        run: unzip livedoc.zip -d doc && unzip doc/livedoc.zip -d doc/doc
+        run: unzip livedoc.zip -d livedoc
+        if: steps.download-doc.outcome == 'success'
 
       - name: Deploy to Netlify
-        id: deploy-netlify
         uses: netlify/actions/cli@master
         with:
-          args: deploy --dir=doc/doc/livedoc --message ${NETLIFY_MESSAGE} --alias ${NETLIFY_ALIAS}
+          args: deploy --dir=livedoc/livedoc --message ${NETLIFY_MESSAGE} --alias ${NETLIFY_ALIAS}
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-          NETLIFY_MESSAGE: Deployed live doc
-          NETLIFY_ALIAS: livedoc
+          NETLIFY_MESSAGE: doc-${{ steps.source-run-info.outputs.targetBranch }}
+          NETLIFY_ALIAS: doc-${{ steps.source-run-info.outputs.targetBranch }}
+        if: steps.download-doc.outcome == 'success'
 
       - name: Report deployment url
+        if: steps.download-doc.outcome == 'success'
         run: |
           echo "::notice::The live documentation has been deployed - ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py
index e0e14d8e785..9ff67bc9ca7 100644
--- a/src/sage_docbuild/conf.py
+++ b/src/sage_docbuild/conf.py
@@ -354,7 +354,7 @@ def set_intersphinx_mappings(app, config):
     for directory in os.listdir(os.path.join(invpath)):
         if directory == 'jupyter_execute':
             # This directory is created by jupyter-sphinx extension for
-            # internal use and should be ignored here. See trac #33507.
+            # internal use and should be ignored here. See Issue #33507.
             continue
         if os.path.isdir(os.path.join(invpath, directory)):
             src = os.path.join(refpath, directory)
@@ -442,7 +442,9 @@ def linkcode_resolve(domain, info):
 }
 
 if not version.split('.')[-1].isnumeric():  # develop version
-    ver = f'<a href="https://livedoc--sagemath.netlify.app/html/en/index.html">{version}</a>'
+    # This URL is hardcoded in the file .github/workflows/doc-publish.yml.
+    # See NETLIFY_ALIAS of the "Deploy to Netlify" step.
+    ver = f'<a href="https://doc-develop--sagemath.netlify.app/html/en/index.html">{version}</a>'
     github_ref = os.environ.get('GITHUB_REF', '')
     if github_ref:
         match = re.search(r'refs/pull/(\d+)/merge', github_ref)
@@ -631,7 +633,7 @@ def linkcode_resolve(domain, info):
 \let\textLaTeX\LaTeX
 \AtBeginDocument{\renewcommand*{\LaTeX}{\hbox{\textLaTeX}}}
 
-% Workaround for a LaTeX bug -- see trac #31397 and
+% Workaround for a LaTeX bug -- see Issue #31397 and
 % https://tex.stackexchange.com/questions/583391/mactex-2020-error-with-report-hyperref-mathbf-in-chapter.
 \makeatletter
 \pdfstringdefDisableCommands{%

From 44c8ac5983b499926097133fcb83feaf8b92b013 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Sun, 23 Jun 2024 23:12:37 +0900
Subject: [PATCH 02/10] No master branch

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

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 81e050df827..0bf2d8f8aac 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -13,7 +13,6 @@ on:
       - '[0-9]+.[0-9]+.rc[0-9]+'
       - '[0-9]+.[0-9]+.[0-9]+.rc[0-9]+'
     branches:
-      - master
       - develop
   workflow_dispatch:
     # Allow to run manually
diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
index ee9de3c8c1c..9d1527d7d31 100644
--- a/.github/workflows/doc-publish.yml
+++ b/.github/workflows/doc-publish.yml
@@ -43,6 +43,7 @@ jobs:
         if: steps.download-doc.outcome == 'success'
 
       - name: Deploy to Netlify
+        id: deploy-netlify
         uses: netlify/actions/cli@master
         with:
           args: deploy --dir=doc/doc --message ${NETLIFY_MESSAGE} --alias ${NETLIFY_ALIAS}
@@ -113,6 +114,7 @@ jobs:
         if: steps.download-doc.outcome == 'success'
 
       - name: Deploy to Netlify
+        id: deploy-netlify
         uses: netlify/actions/cli@master
         with:
           args: deploy --dir=livedoc/livedoc --message ${NETLIFY_MESSAGE} --alias ${NETLIFY_ALIAS}

From 756e89db79a01406889f72861b193410737eb956 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Sun, 23 Jun 2024 23:53:06 +0900
Subject: [PATCH 03/10] Add more if

---
 .github/workflows/doc-publish.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
index 9d1527d7d31..71ea64f2754 100644
--- a/.github/workflows/doc-publish.yml
+++ b/.github/workflows/doc-publish.yml
@@ -69,7 +69,6 @@ jobs:
 
       - name: Update deployment status PR check
         uses: myrotvorets/set-commit-status-action@v2.0.1
-        if: ${{ always() }}
         env:
           DEPLOY_SUCCESS: Successfully deployed preview.
           DEPLOY_FAILURE: Failed to deploy preview.
@@ -80,10 +79,12 @@ jobs:
           context: Deploy Documentation
           targetUrl: ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}
           description: ${{ job.status == 'success' && env.DEPLOY_SUCCESS || env.DEPLOY_FAILURE }}
+        if: steps.download-doc.outcome == 'success'
 
       - name: Report deployment url
         run: |
           echo "::notice::The documentation has been deployed - ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
+        if: steps.download-doc.outcome == 'success'
 
   publish-live-doc:
     runs-on: ubuntu-latest
@@ -126,6 +127,6 @@ jobs:
         if: steps.download-doc.outcome == 'success'
 
       - name: Report deployment url
-        if: steps.download-doc.outcome == 'success'
         run: |
           echo "::notice::The live documentation has been deployed - ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
+        if: steps.download-doc.outcome == 'success'

From 29191d35a4e3fa23dc0e71dbbcae2a45a4156fe3 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Mon, 24 Jun 2024 01:10:33 +0900
Subject: [PATCH 04/10] Fix doc-pdf

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

diff --git a/.github/workflows/doc-build-pdf.yml b/.github/workflows/doc-build-pdf.yml
index b2de526ca94..0c1085138b1 100644
--- a/.github/workflows/doc-build-pdf.yml
+++ b/.github/workflows/doc-build-pdf.yml
@@ -136,13 +136,11 @@ jobs:
         id: copy
         if: (success() || failure()) && steps.docbuild.outcome == 'success'
         run: |
-          # For some reason the deploy step below cannot find /sage/...
-          # So copy everything from there to local folder
           mkdir -p ./doc
-          cp -r -L /sage/local/share/doc/sage/pdf ./doc
+          # We copy everything to a local folder
+          docker cp BUILD:/sage/local/share/doc/sage/pdf doc
           # Zip everything for increased performance
           zip -r doc-pdf.zip doc
-        shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
       - name: Upload doc
         if: (success() || failure()) && steps.copy.outcome == 'success'

From b7bd5d0f3f2b666e7f5789ff841173b521d6e2bd Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Mon, 24 Jun 2024 01:34:13 +0900
Subject: [PATCH 05/10] Only pushes to develop

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

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 0bf2d8f8aac..ff0d20bdba2 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -122,7 +122,7 @@ jobs:
                      ${{ env.BUILD_IMAGE }} /bin/sh
 
       #
-      # On PRs and pushes to master or develop
+      # On PRs and pushes to develop
       #
 
       - name: Store old doc

From ea093f17c4791934cbef41d3837018358dad9285 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Mon, 24 Jun 2024 01:43:06 +0900
Subject: [PATCH 06/10] Add a comment

---
 .github/workflows/doc-publish.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
index 71ea64f2754..1f2d0f67d40 100644
--- a/.github/workflows/doc-publish.yml
+++ b/.github/workflows/doc-publish.yml
@@ -108,6 +108,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repository: ${{ github.repository }}
           run-id: ${{ github.event.workflow_run.id }}
+        # if the doc was built for tag push (targetBranch contains the tag)
         if: steps.source-run-info.outputs.sourceEvent == 'push' && steps.source-run-info.outputs.targetBranch != 'develop'
 
       - name: Extract live doc

From a74cc417cc292f00b447c3415b77e371e63e11cc Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Mon, 24 Jun 2024 08:53:52 +0900
Subject: [PATCH 07/10] Add more comments

---
 .github/workflows/doc-publish.yml | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
index 1f2d0f67d40..0618f2e27b4 100644
--- a/.github/workflows/doc-publish.yml
+++ b/.github/workflows/doc-publish.yml
@@ -1,5 +1,3 @@
-# Triggers after the documentation build has finished,
-# taking the artifact and uploading it to netlify
 name: Publish documentation
 
 on:
@@ -13,6 +11,20 @@ permissions:
   checks: write
   pull-requests: write
 
+
+# This workflow runs after doc-build workflow, taking the artifact
+# (doc/livedoc) and deploying it to a netlify site.
+#
+# event (triggered doc-build)     URL (of the doc deployed to NETLIFY_SITE)
+# ---------------------------     ---------------------------------
+# on pull request                 https://doc-pr-12345--NETLIFY_SITE
+# on push branch develop          https://doc-develop--NETLIFY_SITE
+# on push tag                     https://doc-10-4-beta2--NETLIFY_SITE
+#
+# where NETLIFY_SITE is presently sagemath.netlify.app for repo sagemath/sage.
+#
+# This workflow runs only if secrets NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID are set.
+
 jobs:
   publish-doc:
     runs-on: ubuntu-latest
@@ -54,8 +66,9 @@ jobs:
           NETLIFY_ALIAS: doc-${{ steps.source-run-info.outputs.pullRequestNumber && format('pr-{0}', steps.source-run-info.outputs.pullRequestNumber) || 'develop' }}
         if: steps.download-doc.outcome == 'success'
 
-      # Add deployment as status check, PR comment and annotation
-      # we could use the nwtgck/actions-netlify action for that, except for that it is not (yet) working in workflow_run context: https://github.com/nwtgck/actions-netlify/issues/545
+      # Add deployment as status check, PR comment and annotation we could use
+      # the nwtgck/actions-netlify action for that, except for that it is not
+      # (yet) working in workflow_run context: https://github.com/nwtgck/actions-netlify/issues/545
       - name: Add/Update deployment status PR comment
         uses: marocchino/sticky-pull-request-comment@v2
         with:

From 87161b1cd1387e503c1c38cbce65526bc21ea6ad Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Mon, 24 Jun 2024 09:39:07 +0900
Subject: [PATCH 08/10] Fix random error by replacing rm by mv

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

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index ff0d20bdba2..2b75d84c97c 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -183,7 +183,8 @@ jobs:
           # Restore the new doc from changes by "wipe out"
           (cd doc && git checkout -f)
           # Sometimes rm -rf .git errors out because of some diehard hidden files
-          (cd doc && rm -rf .git 2>/dev/null && rm .gitattributes 2>/dev/null)
+          # So we simply move it out of the doc directory
+          (cd doc && mv .git ../git && mv .gitattributes ../gitattributes)
           mv CHANGES.html doc
           # Zip everything for increased performance
           zip -r doc.zip doc

From 501573ed9081eaa70c51267dbbd090ff2ae244da Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Mon, 24 Jun 2024 15:05:10 +0900
Subject: [PATCH 09/10] Deploy twice to have a way to refer to doc latest

---
 .github/workflows/doc-publish.yml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
index 0618f2e27b4..d5eafc953e1 100644
--- a/.github/workflows/doc-publish.yml
+++ b/.github/workflows/doc-publish.yml
@@ -20,6 +20,7 @@ permissions:
 # on pull request                 https://doc-pr-12345--NETLIFY_SITE
 # on push branch develop          https://doc-develop--NETLIFY_SITE
 # on push tag                     https://doc-10-4-beta2--NETLIFY_SITE
+# on push tag                     https://doc-release--NETLIFY_SITE
 #
 # where NETLIFY_SITE is presently sagemath.netlify.app for repo sagemath/sage.
 #
@@ -128,7 +129,7 @@ jobs:
         run: unzip livedoc.zip -d livedoc
         if: steps.download-doc.outcome == 'success'
 
-      - name: Deploy to Netlify
+      - name: Deploy to netlify with doc-TAG alias
         id: deploy-netlify
         uses: netlify/actions/cli@master
         with:
@@ -140,6 +141,15 @@ jobs:
           NETLIFY_ALIAS: doc-${{ steps.source-run-info.outputs.targetBranch }}
         if: steps.download-doc.outcome == 'success'
 
+      - name: Deploy to netlify with doc-release alias
+        uses: netlify/actions/cli@master
+        with:
+          args: deploy --dir=livedoc/livedoc --message doc-release --alias doc-release
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+        if: steps.download-doc.outcome == 'success'
+
       - name: Report deployment url
         run: |
           echo "::notice::The live documentation has been deployed - ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"

From d2d1514148f46a4ceeea650eab1fd0a0800ebbc9 Mon Sep 17 00:00:00 2001
From: Kwankyu Lee <ekwankyu@gmail.com>
Date: Tue, 25 Jun 2024 16:28:20 +0900
Subject: [PATCH 10/10] Fix broken changes.html

---
 .ci/create-changes-html.sh      |  2 --
 .github/workflows/doc-build.yml | 15 +++++++++------
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/.ci/create-changes-html.sh b/.ci/create-changes-html.sh
index d061c725a68..80335ea1613 100755
--- a/.ci/create-changes-html.sh
+++ b/.ci/create-changes-html.sh
@@ -8,8 +8,6 @@ fi
 BASE_DOC_COMMIT="$1"
 DOC_REPOSITORY="$2"
 
-# Wipe out chronic diffs between old doc and new doc
-(cd $DOC_REPOSITORY && find . -name "*.html" | xargs sed -i -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d')
 # Create CHANGES.html
 echo '<html>' > CHANGES.html
 echo '<head>' >> CHANGES.html
diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
index 2b75d84c97c..0e35de3ce09 100644
--- a/.github/workflows/doc-build.yml
+++ b/.github/workflows/doc-build.yml
@@ -150,7 +150,7 @@ jobs:
            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; \
-           git add -A && git commit --quiet -m "old")
+           git add -A && git commit --quiet -m 'old')
 
       - name: Build doc
         id: docbuild
@@ -175,13 +175,16 @@ jobs:
           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
           (cd doc && git commit -a -m 'new')
-          # Wipe out chronic diffs of new doc against old doc
+          # 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 for/ s/ built with GitHub PR .*. Doc/. Doc/' \
-                                                -e '/<link rel="stylesheet"/ s/?v=[0-9a-f]*"/"/')
-          .ci/create-changes-html.sh $(cd doc && git rev-parse HEAD^) doc
-          # Restore the new doc from changes by "wipe out"
-          (cd doc && git checkout -f)
+                                                -e '/<link rel="stylesheet"/ s/?v=[0-9a-f]*"/"/' \
+                                                -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d' \
+           && 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)
+          .ci/create-changes-html.sh $(cd doc && git rev-parse HEAD~2) doc
+          # Restore the new doc with changes made in create-changes-html.sh but dropping changes by "wipe out"
+          (cd doc && git stash -q && git checkout -q -f HEAD~1 && git stash pop -q)
           # Sometimes rm -rf .git errors out because of some diehard hidden files
           # So we simply move it out of the doc directory
           (cd doc && mv .git ../git && mv .gitattributes ../gitattributes)