From a9decf4a57a11c723e38ce0dd8cdc28485fac98d Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Wed, 3 Jul 2024 10:35:18 +0900 Subject: [PATCH 1/4] Announcement banner also for PRs over stable release --- .github/workflows/doc-build.yml | 88 ++++++++++++++++++++------------- src/sage_docbuild/conf.py | 35 ++++++------- 2 files changed, 72 insertions(+), 51 deletions(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 3305fad3cc7..8f749fed029 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -132,25 +132,35 @@ jobs: git config --global --add safe.directory $(pwd) git config --global user.email "ci-sage@example.com" git config --global user.name "Build documentation workflow" - # 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) - 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 '/;,\;; d') - # 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; \ - git add -A && git commit --quiet -m 'old') + # Check if we are on PR + PR_NUMBER="" + if [[ -n "$GITHUB_REF" ]]; then + if [[ "$GITHUB_REF" =~ refs/pull/([0-9]+)/merge ]]; then + PR_NUMBER="${BASH_REMATCH[1]}" + fi + fi + # If so, then prepare to 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) + 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 '/;,\;; d') + # 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; \ + git add -A && git commit --quiet -m 'old') + fi - name: Build doc id: docbuild @@ -174,21 +184,31 @@ jobs: # 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 - (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 '/;,\;; 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 + # Check if we are on PR + PR_NUMBER="" + if [[ -n "$GITHUB_REF" ]]; then + if [[ "$GITHUB_REF" =~ refs/pull/([0-9]+)/merge ]]; then + PR_NUMBER="${BASH_REMATCH[1]}" + fi + fi + # If so, then create CHANGES.html + if [[ -n "$PR_NUMBER" ]]; then + (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 of/ s/ built with GitHub PR .* for development/ for development/' \ + -e '/;,\;; 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 + fi # Zip everything for increased performance zip -r doc.zip doc diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index fbea163ead3..567140880a5 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -441,26 +441,27 @@ def linkcode_resolve(domain, info): # "source_directory" is defined in conf.py customized for the doc } -if not version.split('.')[-1].isnumeric(): # develop version +# Check the condition for announcement banner +github_ref = os.environ.get('GITHUB_REF', '') +if github_ref: + match = re.search(r'refs/pull/(\d+)/merge', github_ref) + if match: + pr_number = match.group(1) +is_develop_version = not version.split('.')[-1].isnumeric() +is_for_github_pr = github_ref and match and pr_number + +if is_develop_version or is_for_github_pr: # condition for announcement banner # This URL is hardcoded in the file .github/workflows/doc-publish.yml. # See NETLIFY_ALIAS of the "Deploy to Netlify" step. ver = f'{version}' - 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 links - # 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('PR_SHA', '') - pr_commit = pr_url + f'/commits/{pr_sha}' - ver += f' built with GitHub PR #{pr_number}' \ - f' on {pr_sha[:7]}' \ - f' [changes]' - banner = f'This is documentation for Sage development version {ver}. ' \ - 'Documentation for the latest stable version is ' \ - 'here.' + if is_for_github_pr: + pr_url = f'https://github.com/sagemath/sage/pull/{pr_number}' + pr_sha = os.environ.get('PR_SHA', '') + pr_commit = pr_url + f'/commits/{pr_sha}' + ver += f' built with GitHub PR #{pr_number}' \ + f' on {pr_sha[:7]}' \ + f' [changes]' + banner = f'This is documentation of Sage version {ver} for development purpose.' html_theme_options.update({ "announcement": banner }) # The name of the Pygments (syntax highlighting) style to use. This From a51b5715642b0e98fcbbd52fe8882ed75e2d059f Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Wed, 3 Jul 2024 11:07:43 +0900 Subject: [PATCH 2/4] Change 'of' back to 'for' --- src/sage_docbuild/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 567140880a5..0273876b734 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -461,7 +461,7 @@ def linkcode_resolve(domain, info): ver += f' built with GitHub PR #{pr_number}' \ f' on {pr_sha[:7]}' \ f' [changes]' - banner = f'This is documentation of Sage version {ver} for development purpose.' + banner = f'This is documentation for Sage version {ver} for development purpose.' html_theme_options.update({ "announcement": banner }) # The name of the Pygments (syntax highlighting) style to use. This From 9b272c05c7ecc8698ed9ceb0259aead5b042e7b1 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Wed, 3 Jul 2024 14:23:07 +0900 Subject: [PATCH 3/4] Provision for merge before 10.4 release --- src/doc/en/website/versions.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/src/doc/en/website/versions.txt b/src/doc/en/website/versions.txt index 12aed2b8cfe..0fcb63d686a 100644 --- a/src/doc/en/website/versions.txt +++ b/src/doc/en/website/versions.txt @@ -7,7 +7,6 @@ # The sage-update-version script adds a new line for a new stable release # when run by the Sage release manager to prepare a new release # -10.4 doc-10-4--sagemath.netlify.app 10.3 doc-10-3--sagemath.netlify.app 10.2 doc-10-2--sagemath.netlify.app 10.1 doc-10-1--sagemath.netlify.app From 30638a1c93b4fc2697b744879e0846533578f279 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 5 Jul 2024 17:17:02 +0900 Subject: [PATCH 4/4] Delete a spurious space --- src/sage_docbuild/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 0273876b734..50d56ccfd05 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -681,7 +681,7 @@ def add_page_context(app, pagename, templatename, context, doctree): path2 = os.path.join(SAGE_DOC, 'html', 'en') relpath = os.path.relpath(path2, path1) context['release'] = release - context['documentation_title'] = f'Version {release} Documentation ' + context['documentation_title'] = f'Version {release} Documentation' context['documentation_root'] = os.path.join(relpath, 'index.html') if 'website' in path1: context['title'] = 'Documentation'