Improve announcement banner

Author: kwankyu

.github/workflows/doc-build.yml

@@ -129,6 +129,7 @@ jobs:
           # Wipe out chronic diffs between old doc and new doc
           (cd docs && \
            find . -name "*.html" | xargs sed -i -e '/class="sidebar-brand-text"/ s/Sage [0-9a-z.]* /Sage '"$new_version"' /' \
+                                                -e '/This is documentation for/ s/ built with GitHub PR [^.]*././' \
                                                 -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
@@ -143,6 +144,8 @@ jobs:
         # Always non-incremental because of the concern that
         # incremental docbuild may introduce broken links (inter-file references) though build succeeds
         run: |
+          export GITHUB_REF=${{ github.ref }}
+          export GITHUB_SHA=${{ github.sha }}
           export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
           make doc-clean doc-uninstall
           export SAGE_USE_CDNS=yes

.github/workflows/doc-publish.yml

@@ -61,7 +61,7 @@ jobs:
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
           NETLIFY_PRODUCTION: ${{ github.ref == 'refs/heads/develop' }}
           NETLIFY_MESSAGE: ${{ steps.source-run-info.outputs.pullRequestNumber }}
-          NETLIFY_ALIAS: deploy-preview-${{ steps.source-run-info.outputs.pullRequestNumber }}
+          NETLIFY_ALIAS: preview-${{ steps.source-run-info.outputs.pullRequestNumber }}
 
       # 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
@@ -130,7 +130,7 @@ jobs:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
           NETLIFY_MESSAGE: Deployed live doc
-          NETLIFY_ALIAS: deploy-livedoc
+          NETLIFY_ALIAS: livedoc
 
       - name: Report deployment url
         run: |

src/sage_docbuild/conf.py

@@ -20,6 +20,7 @@
 
 import sys
 import os
+import re
 import importlib
 import dateutil.parser
 import sphinx
@@ -441,11 +442,24 @@ def linkcode_resolve(domain, info):
 }
 
 if not version.split('.')[-1].isnumeric():  # develop version
-    html_theme_options.update({
-        "announcement": f'This is documentation for Sage development version {version}. '
-                         'The documentation for the latest stable version is available '
-                         '<a href="https://doc.sagemath.org/html/en/index.html">here</a>.'
-})
+    ver = f'<a href="https://livedoc--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)
+        if match:
+            # As this doc is built for a GitHub PR, we plant a link
+            # to the PR in the announcement banner.
+            pr_number = match.group(1)
+            pr_url = f'https://github.com/sagemath/sage/pull/{pr_number}'
+            pr_sha =  os.environ.get('GITHUB_SHA', '')
+            pr_commit = pr_url + f'/commits/{pr_sha}'
+            ver += f' built with GitHub PR <a href="{pr_url}">#{pr_number}</a>' \
+                   f' on <a href="{pr_commit}">{pr_sha[:7]}</a>' \
+                   f' [<a href="/changes.html">changes</a>]'
+    banner = f'This is documentation for Sage development version {ver}. ' \
+              'Documentation for the latest stable version is ' \
+              '<a href="https://doc.sagemath.org/html/en/index.html">here</a>.'
+    html_theme_options.update({ "announcement": banner })
 
 # The name of the Pygments (syntax highlighting) style to use. This
 # overrides a HTML theme's corresponding setting.