sagemath · vbraun · Jul 4, 2024 · Jun 23, 2024 · Jun 23, 2024 · Jun 23, 2024
diff --git 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
@@ -19,7 +17,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
@@ -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,29 +124,27 @@ 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: |
           export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
           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
+          # We copy everything to a local folder
+          docker cp BUILD:/sage/local/share/doc/sage/pdf doc
           # Zip everything for increased performance
-          zip -r docs-pdf.zip docs
-        shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
+          zip -r doc-pdf.zip doc
 
-      - 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
@@ -4,8 +4,15 @@ 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
   workflow_dispatch:
     # Allow to run manually
@@ -34,7 +41,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 +121,13 @@ jobs:
                      --workdir $(pwd) \
                      ${{ env.BUILD_IMAGE }} /bin/sh
 
-      # Docs
+      #
+      # On PRs and pushes to 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 +137,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")
+           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 +166,47 @@ 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')
-          # Wipe out chronic diffs of new doc against old doc
-          (cd docs && \
+          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 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 docs && git rev-parse HEAD^) docs
-          # 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
+                                                -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)
+          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 +233,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