sagemath · vbraun · Nov 10, 2023 · Oct 31, 2023 · Nov 1, 2023 · Nov 1, 2023
diff --git a/.github/workflows/doc-build-pdf.yml b/.github/workflows/doc-build-pdf.yml
@@ -67,7 +67,7 @@ jobs:
           git config --global user.name "Build & Test workflow"
           .ci/retrofit-worktree.sh worktree-image /sage
           # Keep track of changes to built HTML
-          new_version=$(cat src/VERSION.txt); (cd /sage/local/share/doc/sage/html/en && find . -name "*.html" | xargs sed -i '/class="sidebar-brand-text"/s/Sage [0-9a-z.]* /Sage '$new_version' /'; 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")
+          new_version=$(cat src/VERSION.txt); (cd /sage/local/share/doc/sage/html && find . -name "*.html" | xargs sed -i '/class="sidebar-brand-text"/s/Sage [0-9a-z.]* /Sage '$new_version' /'; 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: Download upstream artifact
         uses: actions/download-artifact@v3
@@ -119,7 +119,7 @@ jobs:
           # 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/en/* ./docs
+          cp -r -L /sage/local/share/doc/sage/pdf ./docs
           # Zip everything for increased performance
           zip -r docs-pdf.zip docs
 

diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
@@ -63,12 +63,12 @@ jobs:
           mathjax_path_to=$(SAGE_USE_CDNS=yes /sage/sage -python -c "from sage_docbuild.conf import mathjax_path; print(mathjax_path)")
           new_version=$(cat src/VERSION.txt)
           # Wipe out chronic diffs between old doc and new doc
-          (cd /sage/local/share/doc/sage/html/en && \
+          (cd /sage/local/share/doc/sage/html && \
            find . -name "*.html" | xargs sed -i -e '/class="sidebar-brand-text"/ s/Sage [0-9a-z.]* /Sage '"$new_version"' /' \
                                                 -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 /sage/local/share/doc/sage/html/en && \
+          (cd /sage/local/share/doc/sage/html && \
            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; \
@@ -116,9 +116,9 @@ jobs:
         run: |
           set -ex
           export SAGE_USE_CDNS=yes
-          mv /sage/local/share/doc/sage/html/en/.git /sage/.git-doc
+          mv /sage/local/share/doc/sage/html/.git /sage/.git-doc
           make doc-clean doc-uninstall
-          mkdir -p /sage/local/share/doc/sage/html/en/ && mv /sage/.git-doc /sage/local/share/doc/sage/html/en/.git
+          mkdir -p /sage/local/share/doc/sage/html/ && mv /sage/.git-doc /sage/local/share/doc/sage/html/.git
           ./config.status && make sagemath_doc_html-no-deps
         working-directory: ./worktree-image
         env:
@@ -131,9 +131,9 @@ jobs:
         run: |
           set -ex
           mkdir -p ./docs
-          (cd /sage/local/share/doc/sage/html/en && git commit -a -m 'new')
+          (cd /sage/local/share/doc/sage/html && git commit -a -m 'new')
           # Wipe out chronic diffs between old doc and new doc
-          (cd /sage/local/share/doc/sage/html/en && \
+          (cd /sage/local/share/doc/sage/html && \
            find . -name "*.html" | xargs sed -i -e '\;<script type="application/vnd\.jupyter\.widget-state+json">;,\;</script>; d')
           # Create CHANGES.html
           echo '<html>' > ./docs/CHANGES.html
@@ -162,7 +162,7 @@ jobs:
           EOF
           echo '</head>' >> ./docs/CHANGES.html
           echo '<body>' >> ./docs/CHANGES.html
-          (cd /sage/local/share/doc/sage/html/en && git diff HEAD^; rm -rf .git) > ./docs/diff.txt
+          (cd /sage/local/share/doc/sage/html && git diff HEAD^ -- *.html; rm -rf .git) > ./docs/diff.txt
           /sage/sage -python - << EOF
           import re, html
           with open('./docs/diff.txt', 'r') as f:
@@ -172,7 +172,7 @@ jobs:
               for block in diff_blocks:
                   match = re.search(r'^diff --git a/(.*) b/\1', block, flags=re.MULTILINE)
                   if match:
-                      path = match.group(1)
+                      path = 'html/' + match.group(1)
                       out_blocks.append(f'<p class="diff"><a href="{path}">{path}</a>&emsp;</p>\n<pre><code class="language-diff">' + html.escape(block).strip() + '</code></pre>')
               output_text = '\n'.join(out_blocks)
           with open('./docs/diff.html', 'w') as f:
@@ -182,11 +182,12 @@ jobs:
           echo '</body>' >> ./docs/CHANGES.html
           echo '</html>' >>./docs/CHANGES.html
           rm ./docs/diff.txt ./docs/diff.html
-          (cd /sage/local/share/doc/sage/html/en && git reset --hard HEAD)
+          (cd /sage/local/share/doc/sage/html && git reset --hard HEAD)
           # For some reason the deploy step below cannot find /sage/...
           # So copy everything from there to local folder
           # We also need to replace the symlinks because netlify is not following them
-          cp -r -L /sage/local/share/doc/sage/html/en/* ./docs
+          cp -r -L /sage/local/share/doc/sage/html ./docs
+          cp  /sage/local/share/doc/sage/index.html ./docs
           # Zip everything for increased performance
           zip -r docs.zip docs
 
@@ -196,3 +197,36 @@ jobs:
         with:
           name: docs
           path: docs.zip
+
+      - name: Build live doc
+        id: buildlivedoc
+        if: (success() || failure()) && steps.copy.outcome == 'success' && github.repository == 'sagemath/sage' && github.ref == 'refs/heads/develop'
+        run: |
+          set -ex
+          export SAGE_USE_CDNS=yes
+          export SAGE_LIVE_DOC=yes
+          export SAGE_JUPYTER_SERVER=binder:sagemath/sage-binder-env/dev
+          make doc-clean doc-uninstall
+          ./config.status && make sagemath_doc_html-no-deps
+        working-directory: ./worktree-image
+        env:
+          MAKE: make -j2 --output-sync=recurse
+          SAGE_NUM_THREADS: 2
+
+      - name: Copy live doc
+        id: copylivedoc
+        if: (success() || failure()) && steps.buildlivedoc.outcome == 'success'
+        run: |
+          set -ex
+          mkdir -p ./livedoc
+          cp -r -L /sage/local/share/doc/sage/html ./livedoc
+          cp  /sage/local/share/doc/sage/index.html ./livedoc
+          zip -r livedoc.zip livedoc
+
+      - name: Upload live doc
+        if: (success() || failure()) && steps.copylivedoc.outcome == 'success'
+        uses: actions/upload-artifact@v3
+        with:
+          name: livedoc
+          path: livedoc.zip
+
diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml
@@ -72,7 +72,7 @@ jobs:
           header: preview-comment
           recreate: true
           message: |
-            [Documentation preview for this PR](${{ steps.deploy-netlify.outputs.NETLIFY_URL }}) (built with commit ${{ steps.source-run-info.outputs.sourceHeadSha }}; [changes](${{ steps.deploy-netlify.outputs.NETLIFY_URL }}/CHANGES.html)) is ready! :tada:
+            [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:
 
       - name: Update deployment status PR check
         uses: myrotvorets/[email protected]
@@ -90,5 +90,48 @@ jobs:
 
       - name: Report deployment url
         run: |
-          echo "::notice::The documentation has being automatically deployed to Netlify. %0A ✅ Preview: ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
+          echo "::notice::The documentation has been deployed - ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
+
+  publish-live-doc:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'develop'
+    steps:
+      - name: Download live doc
+        uses: actions/[email protected]
+        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: Extract live doc
+        run: unzip livedoc.zip -d doc && unzip doc/livedoc.zip -d doc/doc
+
+      - 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}
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_MESSAGE: Deployed live doc
+          NETLIFY_ALIAS: deploy-livedoc
+
+      - name: Report deployment url
+        run: |
+          echo "::notice::The live documentation has been deployed - ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
 
diff --git a/src/sage/misc/sageinspect.py b/src/sage/misc/sageinspect.py
@@ -1806,6 +1806,7 @@ def formatannotation(annotation, base_module=None):
         return annotation.__module__ + '.' + annotation.__qualname__
     return repr(annotation)
 
+_formatannotation = formatannotation
 
 def sage_formatargspec(args, varargs=None, varkw=None, defaults=None,
                        kwonlyargs=(), kwonlydefaults=None, annotations={},
@@ -1814,7 +1815,7 @@ def sage_formatargspec(args, varargs=None, varkw=None, defaults=None,
                        formatvarkw=None,
                        formatvalue=None,
                        formatreturns=None,
-                       formatannotation=formatannotation):
+                       formatannotation=None):
     """
     Format an argument spec from the values returned by getfullargspec.
 
@@ -1851,6 +1852,8 @@ def sage_formatargspec(args, varargs=None, varkw=None, defaults=None,
         formatvalue = lambda value: '=' + repr(value)
     if formatreturns is None:
         formatreturns = lambda text: ' -> ' + text
+    if formatannotation is None:
+        formatannotation = _formatannotation
 
     def formatargandannotation(arg):
         result = formatarg(arg)