From fd92c05bc95fc663dbe2838283e7677102d2f7de Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 23 Jun 2024 22:14:34 +0900 Subject: [PATCH 01/32] 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 '' >> CHANGES.html cat >> CHANGES.html << EOF ; 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 '//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'{version}' + # 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) @@ -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 748ff77ab3224dcc6324f34fa95d48f66b1f6de9 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 23 Jun 2024 23:12:37 +0900 Subject: [PATCH 02/32] 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 fd314530028b877e248ccccc843c851ed970693e Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 23 Jun 2024 23:53:06 +0900 Subject: [PATCH 03/32] 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 e7a64ff00e435259ce1a297582d1f85ec9ba4b31 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 24 Jun 2024 01:10:33 +0900 Subject: [PATCH 04/32] 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 7fa8c480491c6e77dc00099a803f4a57a3428d44 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 24 Jun 2024 01:34:13 +0900 Subject: [PATCH 05/32] 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 6e64826a7aa1da91bbb5361314d624891dd65f02 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 24 Jun 2024 01:43:06 +0900 Subject: [PATCH 06/32] 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 10f0fa6cf2002aefc483769b98eb4a02247424ac Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 24 Jun 2024 08:53:52 +0900 Subject: [PATCH 07/32] 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 13740649671847210eaf912d8f3db025c84e1366 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 24 Jun 2024 09:39:07 +0900 Subject: [PATCH 08/32] 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 11ce8cc387fae71762e81185ac675cd154bb82f8 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 24 Jun 2024 15:05:10 +0900 Subject: [PATCH 09/32] 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 c2eb28c09e3f96ffdd24da833b859eac561c527e Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Tue, 25 Jun 2024 16:28:20 +0900 Subject: [PATCH 10/32] 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 '\;; d') # Create CHANGES.html echo '' > CHANGES.html echo '' >> 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 '/;,\;; 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) From 990ac7d785b59bfb265ee45d65b07f205935749c Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Thu, 27 Jun 2024 17:24:49 +0900 Subject: [PATCH 11/32] Add version selector --- .github/workflows/doc-build.yml | 2 +- src/bin/sage-update-version | 20 +++++ src/doc/common/static/custom-furo.css | 43 ++++++++++- .../common/static/custom-jupyter-sphinx.css | 72 +++++++++--------- src/doc/common/static/jupyter-sphinx-furo.js | 73 +++++++++++++++++++ .../sidebar/version-selector.html | 3 + src/doc/versions.txt | 17 +++++ src/sage_docbuild/conf.py | 1 + 8 files changed, 191 insertions(+), 40 deletions(-) create mode 100644 src/doc/common/templates-furo/sidebar/version-selector.html create mode 100644 src/doc/versions.txt diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 0e35de3ce09..3305fad3cc7 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -228,7 +228,7 @@ jobs: # We copy everything to a local folder docker cp --follow-link BUILD:/sage/local/share/doc/sage/html livedoc docker cp --follow-link BUILD:/sage/local/share/doc/sage/pdf livedoc - docker cp BUILD:/sage/local/share/doc/sage/index.html livedoc + docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html livedoc zip -r livedoc.zip livedoc - name: Upload live doc diff --git a/src/bin/sage-update-version b/src/bin/sage-update-version index c6680918a36..d4ae6ae3742 100755 --- a/src/bin/sage-update-version +++ b/src/bin/sage-update-version @@ -112,6 +112,25 @@ export SAGE_VERSION export SAGE_RELEASE_DATE envsubst <"$SAGE_ROOT/CITATION.cff.in" >"$SAGE_ROOT/CITATION.cff" +# Update src/doc/versions.txt file storing the URLs of the docs for the recent stable releases +if [[ $SAGE_VERSION =~ ^[0-9]+(\.[0-9]+)*$ ]]; then + file_path="$SAGE_ROOT/src/doc/versions.txt" + # Extract the most recent version line from versions.txt; the first line is a comment + line_number=$(grep -n '^[0-9]' "$file_path" | head -n 1 | cut -d: -f1) + version_line=$(sed -n "${line_number}p" "$file_path") + domain=${version_line#*--} + version=${SAGE_VERSION//./-} + # For the origin of this format, see .github/workflows/doc-publish.yml + url="doc-$version--$domain" + # Add new line to versions.txt + sed -i "${line_number}i $SAGE_VERSION $url" "$file_path" + # If the number of version lines is more than 10, remove the last line + line_count=$(grep -c '^[0-9]' "$file_path") + if [ "$line_count" -gt 10 ]; then + sed -i '$ d' "$file_path" + fi +fi + # Commit auto-generated changes git commit -m "Updated SageMath version to $SAGE_VERSION" -- \ "$SAGE_ROOT/VERSION.txt" \ @@ -124,6 +143,7 @@ git commit -m "Updated SageMath version to $SAGE_VERSION" -- \ "$SAGE_ROOT/build/pkgs/*/version_requirements.txt" \ "$SAGE_ROOT"/pkgs/*/VERSION.txt \ "$SAGE_ROOT/.upstream.d/20-github.com-sagemath-sage-releases" \ + "$SAGE_ROOT/src/doc/versions.txt" \ || die "Error committing to the repository." git tag -a "$SAGE_VERSION" -m "$SAGE_VERSION_BANNER" \ diff --git a/src/doc/common/static/custom-furo.css b/src/doc/common/static/custom-furo.css index ae75c2b6383..0aff44252cf 100644 --- a/src/doc/common/static/custom-furo.css +++ b/src/doc/common/static/custom-furo.css @@ -24,14 +24,51 @@ a.pdf:hover { /* Style for announcement banner */ .announcement { - background: orange; + background: orange; } .announcement-content { - color: black; + color: black; } .announcement-content a { + color: white; + text-decoration: none; +} + +/* Style for the floating versions menu */ + +.sidebar-drawer { + z-index: 100; +} + +#versions-menu { + position: fixed; + bottom: 10px; + right: 10px; + padding: 5px; + font-size: small; + opacity: 1; + background-color: white; + color: blue; +} + +body[data-theme="dark"] { + #versions-menu { + background-color: black; color: white; - text-decoration: none; + } +} + +@media (prefers-color-scheme: dark) { + body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */ + #versions-menu { + background-color: black; + color: white; + } + } +} + +#versions-menu:hover { + opacity: 1 } diff --git a/src/doc/common/static/custom-jupyter-sphinx.css b/src/doc/common/static/custom-jupyter-sphinx.css index 7e090b5e08d..482a2ddaed2 100644 --- a/src/doc/common/static/custom-jupyter-sphinx.css +++ b/src/doc/common/static/custom-jupyter-sphinx.css @@ -96,41 +96,41 @@ body[data-theme="dark"] { } @media (prefers-color-scheme: dark) { - body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */ - .jupyter_container { - color: white; - background-color: black; - } - - .jupyter_container .highlight { - background-color: black; - } - - .thebelab-button { - color: #d0d0d0; - background-color: #383838; - } - - .thebelab-button:active { - color: #368ce2; - } - - #thebelab-activate-button { - background-color: #383838; - } - - #thebelab-activate-button:active { - color: #368ce2; - } - - .thebelab-cell .jp-OutputArea-output { - color: white; - background-color: black; - } - - .thebelab-cell .jp-OutputArea-output pre { - color: white; - background-color: black; + body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */ + .jupyter_container { + color: white; + background-color: black; + } + + .jupyter_container .highlight { + background-color: black; + } + + .thebelab-button { + color: #d0d0d0; + background-color: #383838; + } + + .thebelab-button:active { + color: #368ce2; + } + + #thebelab-activate-button { + background-color: #383838; + } + + #thebelab-activate-button:active { + color: #368ce2; + } + + .thebelab-cell .jp-OutputArea-output { + color: white; + background-color: black; + } + + .thebelab-cell .jp-OutputArea-output pre { + color: white; + background-color: black; + } } - } } diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index a43a7c8b122..3869c20a4d7 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -58,6 +58,79 @@ const observer2 = new MutationObserver(callback); observer2.observe(document.getElementsByClassName("content")[0], { childList: true, subtree: true }); +// +// Version selector +// + +var versionMap = {}; + +async function fetchVersions() { + try { + let versions_file = "https://raw.githubusercontent.com/sagemath/sage/develop/src/doc/versions.txt" + let response = await fetch(versions_file); + if (!response.ok) { + throw new Error('Network response was not ok'); + } + let text = await response.text(); + let lines = text.split('\n'); + + // Parse the versions.txt file + lines.forEach(line => { + if (!line.startsWith('#')) { // Ignore the comment line + let [ver, url] = line.split(' '); + if (ver && url) { + if (!url.startsWith("https://")) { + url = "https://" + url; + } + versionMap[ver] = url; + } + } + }); + } catch (error) { + console.error("Failed to fetch versions.txt file:", error); + } + + if (Object.keys(versionMap).length > 0) { + // Populate the versions menu + let dropdown = document.getElementById("versions-menu"); + Object.keys(versionMap).forEach(ver => { + let option = document.createElement("option"); + option.value = ver; + option.text = ver; + dropdown.add(option); + }); + } else { + document.getElementById('versions-menu').style.display = 'none'; + } + + let urlParams = new URLSearchParams(window.location.search); + let version = urlParams.get("ver"); + // Check if the version exists in the map and redirect + if (version in versionMap) { + let targetUrl = versionMap[version]; + window.location.href = targetUrl + window.location.pathname; + } else { + console.error("Version not found in versions.txt."); + } +} + +fetchVersions() + +// Function to change the version based on versions menu selection +function changeVersion() { + let selectedVersion = document.getElementById("versions-menu").value; + if (selectedVersion) { + // Check if the version exists in the map and redirect + if (selectedVersion in versionMap) { + let targetUrl = versionMap[selectedVersion]; + window.location.href = targetUrl + window.location.pathname; + } else { + console.error("Version not found in versions.txt."); + } + } +} + + // Listen to the kernel status changes // https://thebe.readthedocs.io/en/stable/events.html thebelab.on("status", function (evt, data) { diff --git a/src/doc/common/templates-furo/sidebar/version-selector.html b/src/doc/common/templates-furo/sidebar/version-selector.html new file mode 100644 index 00000000000..3d79a0cf0e9 --- /dev/null +++ b/src/doc/common/templates-furo/sidebar/version-selector.html @@ -0,0 +1,3 @@ + diff --git a/src/doc/versions.txt b/src/doc/versions.txt new file mode 100644 index 00000000000..582199e6a85 --- /dev/null +++ b/src/doc/versions.txt @@ -0,0 +1,17 @@ +# This file is used by the version selector of the sage doc +# and updated by the script src/bin/sage-update-version +# run by the release manager to prepare a new release +# +# The first line is reserved for develop version +# The other lines are for recent stable releases (at most 10 lines) +# A line consists of the version and the URL to the doc +# +# The sage-update-version script adds a new line for a new stable release +# +# Do not edit manually +dev doc-release--sagemath.netlify.app +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 +10.0 doc-10-0--sagemath.netlify.app diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 9ff67bc9ca7..603314ff1b4 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -474,6 +474,7 @@ def linkcode_resolve(domain, info): "sidebar/scroll-start.html", "sidebar/brand.html", "sidebar/search.html", + "sidebar/version-selector.html", "sidebar/home.html", "sidebar/navigation.html", "sidebar/ethical-ads.html", From e06401afb535cf6e194dacc3a3232a41a7be3f93 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 30 Jun 2024 11:52:00 +0900 Subject: [PATCH 12/32] Add current version at top --- src/doc/common/static/jupyter-sphinx-furo.js | 18 ++++++++++++++++++ .../sidebar/version-selector.html | 1 - 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 3869c20a4d7..a2b8342005c 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -74,6 +74,24 @@ async function fetchVersions() { let text = await response.text(); let lines = text.split('\n'); + let url = window.location.origin; + let start_index = url.indexOf('doc-') + 4; + let end_index = url.indexOf('--'); + let version_string = url.substring(start_index, end_index); + let current_version + + // Consult the comment in .github/workflows/doc-publish.yml + if (/^pr-\d+$/.test(version_string)) { + current_version = version_string.replace(/-/g, ' '); + } else if (version_string === 'release') { + current_version = 'latest'; + } else if (version_string === 'develop') { + current_version = 'develop'; + } else { + current_version = version_string.replace(/-/g, '.'); + } + versionMap[current_version] = url + // Parse the versions.txt file lines.forEach(line => { if (!line.startsWith('#')) { // Ignore the comment line diff --git a/src/doc/common/templates-furo/sidebar/version-selector.html b/src/doc/common/templates-furo/sidebar/version-selector.html index 3d79a0cf0e9..14d248a5d37 100644 --- a/src/doc/common/templates-furo/sidebar/version-selector.html +++ b/src/doc/common/templates-furo/sidebar/version-selector.html @@ -1,3 +1,2 @@ From 4d75b1b730e4cfd74d9099bf689231fd8d1720ac Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 01:12:50 +0900 Subject: [PATCH 13/32] Add more old docs --- src/doc/versions.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/doc/versions.txt b/src/doc/versions.txt index 582199e6a85..b963bcbd4ca 100644 --- a/src/doc/versions.txt +++ b/src/doc/versions.txt @@ -15,3 +15,6 @@ dev doc-release--sagemath.netlify.app 10.2 doc-10-2--sagemath.netlify.app 10.1 doc-10-1--sagemath.netlify.app 10.0 doc-10-0--sagemath.netlify.app +9.8 doc-9-8--sagemath.netlify.app +9.7 doc-9-7--sagemath.netlify.app +9.6 doc-9-6--sagemath.netlify.app From 99de93fd6151ad6c2b8f10192703a79a33f566ff Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 10:15:57 +0900 Subject: [PATCH 14/32] Fetch versions.txt from doc-release--sagemath.netlify.app --- src/doc/common/static/jupyter-sphinx-furo.js | 3 ++- src/sage_docbuild/builders.py | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index a2b8342005c..671679aaee9 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -66,7 +66,8 @@ var versionMap = {}; async function fetchVersions() { try { - let versions_file = "https://raw.githubusercontent.com/sagemath/sage/develop/src/doc/versions.txt" + // For the origin of this site, see .github/workflows/doc-publish.yml + let versions_file = "https://doc-release--sagemath.netlify.app/versions.txt" let response = await fetch(versions_file); if (!response.ok) { throw new Error('Network response was not ok'); diff --git a/src/sage_docbuild/builders.py b/src/sage_docbuild/builders.py index 967616e2e28..23155df0112 100644 --- a/src/sage_docbuild/builders.py +++ b/src/sage_docbuild/builders.py @@ -455,6 +455,11 @@ def html(self): shutil.copy2(os.path.join(SAGE_DOC_SRC, self.lang, 'website', 'root_index.html'), root_index_file) + # The file versions.txt is used by src/doc/common/static/jupyter-sphinx-furo.js + # for doc version selector + from sage.env import SAGE_DOC + shutil.copy2(os.path.join(SAGE_DOC_SRC, 'versions.txt'), SAGE_DOC) + def pdf(self): """ Build the website hosting pdf docs. From c8339a83023fbd9f98d5a6f28051e5dfcce670b7 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 13:13:28 +0900 Subject: [PATCH 15/32] Store versions.txt in src/doc/en/website --- src/bin/sage-update-version | 4 ++-- src/doc/common/static/jupyter-sphinx-furo.js | 2 +- src/doc/{ => en/website}/versions.txt | 1 + src/sage_docbuild/builders.py | 15 +++++++-------- 4 files changed, 11 insertions(+), 11 deletions(-) rename src/doc/{ => en/website}/versions.txt (95%) diff --git a/src/bin/sage-update-version b/src/bin/sage-update-version index d4ae6ae3742..7d735c12e6c 100755 --- a/src/bin/sage-update-version +++ b/src/bin/sage-update-version @@ -114,7 +114,7 @@ envsubst <"$SAGE_ROOT/CITATION.cff.in" >"$SAGE_ROOT/CITATION.cff" # Update src/doc/versions.txt file storing the URLs of the docs for the recent stable releases if [[ $SAGE_VERSION =~ ^[0-9]+(\.[0-9]+)*$ ]]; then - file_path="$SAGE_ROOT/src/doc/versions.txt" + file_path="$SAGE_ROOT/src/doc/en/website/versions.txt" # Extract the most recent version line from versions.txt; the first line is a comment line_number=$(grep -n '^[0-9]' "$file_path" | head -n 1 | cut -d: -f1) version_line=$(sed -n "${line_number}p" "$file_path") @@ -143,7 +143,7 @@ git commit -m "Updated SageMath version to $SAGE_VERSION" -- \ "$SAGE_ROOT/build/pkgs/*/version_requirements.txt" \ "$SAGE_ROOT"/pkgs/*/VERSION.txt \ "$SAGE_ROOT/.upstream.d/20-github.com-sagemath-sage-releases" \ - "$SAGE_ROOT/src/doc/versions.txt" \ + "$SAGE_ROOT/src/doc/en/website/versions.txt" \ || die "Error committing to the repository." git tag -a "$SAGE_VERSION" -m "$SAGE_VERSION_BANNER" \ diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 671679aaee9..f513ec8be8d 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -67,7 +67,7 @@ var versionMap = {}; async function fetchVersions() { try { // For the origin of this site, see .github/workflows/doc-publish.yml - let versions_file = "https://doc-release--sagemath.netlify.app/versions.txt" + let versions_file = "https://doc-release--sagemath.netlify.app/html/en/versions.txt" let response = await fetch(versions_file); if (!response.ok) { throw new Error('Network response was not ok'); diff --git a/src/doc/versions.txt b/src/doc/en/website/versions.txt similarity index 95% rename from src/doc/versions.txt rename to src/doc/en/website/versions.txt index b963bcbd4ca..68897d2ad99 100644 --- a/src/doc/versions.txt +++ b/src/doc/en/website/versions.txt @@ -10,6 +10,7 @@ # # Do not edit manually dev doc-release--sagemath.netlify.app +10.5 doc-10-5--sagemath.netlify.app 10.4 doc-10-4--sagemath.netlify.app 10.3 doc-10-3--sagemath.netlify.app 10.2 doc-10-2--sagemath.netlify.app diff --git a/src/sage_docbuild/builders.py b/src/sage_docbuild/builders.py index 23155df0112..871cc4705a2 100644 --- a/src/sage_docbuild/builders.py +++ b/src/sage_docbuild/builders.py @@ -442,6 +442,11 @@ def html(self): """ super().html() html_output_dir = self._output_dir('html') + + # This file is used by src/doc/common/static/jupyter-sphinx-furo.js + # for doc version selector + shutil.copy2(os.path.join(self.dir, 'versions.txt'), html_output_dir) + for f in os.listdir(html_output_dir): src = os.path.join(html_output_dir, f) dst = os.path.join(html_output_dir, '..', f) @@ -451,14 +456,8 @@ def html(self): else: shutil.copy2(src, dst) - root_index_file = os.path.join(html_output_dir, '../../../index.html') - shutil.copy2(os.path.join(SAGE_DOC_SRC, self.lang, 'website', 'root_index.html'), - root_index_file) - - # The file versions.txt is used by src/doc/common/static/jupyter-sphinx-furo.js - # for doc version selector - from sage.env import SAGE_DOC - shutil.copy2(os.path.join(SAGE_DOC_SRC, 'versions.txt'), SAGE_DOC) + shutil.copy2(os.path.join(self.dir, 'root_index.html'), + os.path.join(html_output_dir, '../../../index.html')) def pdf(self): """ From a14b215bf399bda45cafac702f07ffefc8aace86 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 13:31:04 +0900 Subject: [PATCH 16/32] Initially do not display selector --- src/doc/common/static/custom-furo.css | 1 + src/doc/common/static/jupyter-sphinx-furo.js | 9 +++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/doc/common/static/custom-furo.css b/src/doc/common/static/custom-furo.css index 0aff44252cf..3ec5578be00 100644 --- a/src/doc/common/static/custom-furo.css +++ b/src/doc/common/static/custom-furo.css @@ -43,6 +43,7 @@ a.pdf:hover { } #versions-menu { + display: none; position: fixed; bottom: 10px; right: 10px; diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index f513ec8be8d..194f396e6a0 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -109,17 +109,18 @@ async function fetchVersions() { console.error("Failed to fetch versions.txt file:", error); } + let menu = document.getElementById("versions-menu"); + if (Object.keys(versionMap).length > 0) { - // Populate the versions menu - let dropdown = document.getElementById("versions-menu"); Object.keys(versionMap).forEach(ver => { let option = document.createElement("option"); option.value = ver; option.text = ver; - dropdown.add(option); + menu.add(option); }); + menu.style.display = 'block'; } else { - document.getElementById('versions-menu').style.display = 'none'; + menu.style.display = 'none'; } let urlParams = new URLSearchParams(window.location.search); From 0ef948c269570cc87832da6ca2c140835dc53961 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 15:02:49 +0900 Subject: [PATCH 17/32] Small fix --- src/doc/common/static/jupyter-sphinx-furo.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 194f396e6a0..3c55ce9e631 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -67,7 +67,7 @@ var versionMap = {}; async function fetchVersions() { try { // For the origin of this site, see .github/workflows/doc-publish.yml - let versions_file = "https://doc-release--sagemath.netlify.app/html/en/versions.txt" + let versions_file = "https://doc-release--sagemath.netlify.app/html/en/versions.txt"; let response = await fetch(versions_file); if (!response.ok) { throw new Error('Network response was not ok'); From 2350f16254ca4509f2a213caa90f557d05e6adcc Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 16:57:06 +0900 Subject: [PATCH 18/32] Add _headers file to avoid CORS problem --- .github/workflows/doc-publish.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml index d5eafc953e1..5454519a6fb 100644 --- a/.github/workflows/doc-publish.yml +++ b/.github/workflows/doc-publish.yml @@ -129,6 +129,16 @@ jobs: run: unzip livedoc.zip -d livedoc if: steps.download-doc.outcome == 'success' + - name: Create _headers file for permissive CORS + run: | + cat < livedoc/livedoc/_headers + /* + Access-Control-Allow-Origin: * + Access-Control-Allow-Methods: GET + Access-Control-Allow-Headers: Content-Type + EOF + if: steps.download-doc.outcome == 'success' + - name: Deploy to netlify with doc-TAG alias id: deploy-netlify uses: netlify/actions/cli@master From 2f509c2da84d115ff56cf8d80591582e11a026b1 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 22:01:30 +0900 Subject: [PATCH 19/32] Improve style --- src/doc/common/static/custom-furo.css | 5 +-- src/doc/common/static/jupyter-sphinx-furo.js | 38 ++++++++++---------- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/src/doc/common/static/custom-furo.css b/src/doc/common/static/custom-furo.css index 3ec5578be00..449b577fe18 100644 --- a/src/doc/common/static/custom-furo.css +++ b/src/doc/common/static/custom-furo.css @@ -43,7 +43,7 @@ a.pdf:hover { } #versions-menu { - display: none; + display: block; position: fixed; bottom: 10px; right: 10px; @@ -70,6 +70,3 @@ body[data-theme="dark"] { } } -#versions-menu:hover { - opacity: 1 -} diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 3c55ce9e631..8834c1dd328 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -75,21 +75,26 @@ async function fetchVersions() { let text = await response.text(); let lines = text.split('\n'); - let url = window.location.origin; - let start_index = url.indexOf('doc-') + 4; - let end_index = url.indexOf('--'); - let version_string = url.substring(start_index, end_index); - let current_version - - // Consult the comment in .github/workflows/doc-publish.yml - if (/^pr-\d+$/.test(version_string)) { - current_version = version_string.replace(/-/g, ' '); - } else if (version_string === 'release') { - current_version = 'latest'; - } else if (version_string === 'develop') { - current_version = 'develop'; + if (window.location.protocol == 'file:') { + current_version = 'local' + url = window.location.href } else { - current_version = version_string.replace(/-/g, '.'); + let url = window.location.origin; + let start_index = url.indexOf('doc-') + 4; + let end_index = url.indexOf('--'); + let version_string = url.substring(start_index, end_index); + let current_version + + // Consult the comment in .github/workflows/doc-publish.yml + if (/^pr-\d+$/.test(version_string)) { + current_version = version_string.replace(/-/g, ' '); + } else if (version_string === 'release') { + current_version = 'latest'; + } else if (version_string === 'develop') { + current_version = 'develop'; + } else { + current_version = version_string.replace(/-/g, '.'); + } } versionMap[current_version] = url @@ -118,7 +123,6 @@ async function fetchVersions() { option.text = ver; menu.add(option); }); - menu.style.display = 'block'; } else { menu.style.display = 'none'; } @@ -126,11 +130,9 @@ async function fetchVersions() { let urlParams = new URLSearchParams(window.location.search); let version = urlParams.get("ver"); // Check if the version exists in the map and redirect - if (version in versionMap) { + if (version && version in versionMap) { let targetUrl = versionMap[version]; window.location.href = targetUrl + window.location.pathname; - } else { - console.error("Version not found in versions.txt."); } } From bb228b38bdfd01a4df6f61e3b15fd840aa796b8a Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 22:21:29 +0900 Subject: [PATCH 20/32] Fix versions.txt --- 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 68897d2ad99..b963bcbd4ca 100644 --- a/src/doc/en/website/versions.txt +++ b/src/doc/en/website/versions.txt @@ -10,7 +10,6 @@ # # Do not edit manually dev doc-release--sagemath.netlify.app -10.5 doc-10-5--sagemath.netlify.app 10.4 doc-10-4--sagemath.netlify.app 10.3 doc-10-3--sagemath.netlify.app 10.2 doc-10-2--sagemath.netlify.app From c3dc3c1db98f457b002075c1d6d7f8d24e1ea9c4 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Mon, 1 Jul 2024 23:35:05 +0900 Subject: [PATCH 21/32] Fix errors --- src/doc/common/static/jupyter-sphinx-furo.js | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 8834c1dd328..b086a5c27ea 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -75,15 +75,16 @@ async function fetchVersions() { let text = await response.text(); let lines = text.split('\n'); + let url = window.location.origin; + let current_version + if (window.location.protocol == 'file:') { - current_version = 'local' - url = window.location.href + current_version = 'local'; + url = window.location.href; } else { - let url = window.location.origin; let start_index = url.indexOf('doc-') + 4; let end_index = url.indexOf('--'); let version_string = url.substring(start_index, end_index); - let current_version // Consult the comment in .github/workflows/doc-publish.yml if (/^pr-\d+$/.test(version_string)) { @@ -140,11 +141,11 @@ fetchVersions() // Function to change the version based on versions menu selection function changeVersion() { - let selectedVersion = document.getElementById("versions-menu").value; - if (selectedVersion) { + let selected_version = document.getElementById("versions-menu").value; + if (selected_version) { // Check if the version exists in the map and redirect - if (selectedVersion in versionMap) { - let targetUrl = versionMap[selectedVersion]; + if (selected_version in versionMap) { + let targetUrl = versionMap[selected_version]; window.location.href = targetUrl + window.location.pathname; } else { console.error("Version not found in versions.txt."); From 687c4f06ed1e79ad3787e585736f3662c859c4a1 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Tue, 2 Jul 2024 16:52:09 +0900 Subject: [PATCH 22/32] Put version selector in the left sidebar --- src/doc/common/static/custom-furo.css | 27 ++++++++++++------- .../sidebar/version-selector.html | 5 ++-- src/sage_docbuild/conf.py | 6 ++--- 3 files changed, 24 insertions(+), 14 deletions(-) diff --git a/src/doc/common/static/custom-furo.css b/src/doc/common/static/custom-furo.css index 449b577fe18..ba71d3d6b0f 100644 --- a/src/doc/common/static/custom-furo.css +++ b/src/doc/common/static/custom-furo.css @@ -43,21 +43,31 @@ a.pdf:hover { } #versions-menu { - display: block; - position: fixed; - bottom: 10px; - right: 10px; - padding: 5px; + display: inline-block; font-size: small; opacity: 1; - background-color: white; - color: blue; + border: none; + background-color: transparent; + color: var(--color-sidebar-link-text--top-level);; +} + +#versions-menu:focus { + outline: none; +} + +.select-wrapper { + display: block; + text-align: center; +} + +.select-wrapper::before { + content: "switch to"; + font-size: small; } body[data-theme="dark"] { #versions-menu { background-color: black; - color: white; } } @@ -65,7 +75,6 @@ body[data-theme="dark"] { body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */ #versions-menu { background-color: black; - color: white; } } } diff --git a/src/doc/common/templates-furo/sidebar/version-selector.html b/src/doc/common/templates-furo/sidebar/version-selector.html index 14d248a5d37..bd18e666d88 100644 --- a/src/doc/common/templates-furo/sidebar/version-selector.html +++ b/src/doc/common/templates-furo/sidebar/version-selector.html @@ -1,2 +1,3 @@ - +
+ +
diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 603314ff1b4..fbea163ead3 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -473,8 +473,8 @@ def linkcode_resolve(domain, info): "**": [ "sidebar/scroll-start.html", "sidebar/brand.html", - "sidebar/search.html", "sidebar/version-selector.html", + "sidebar/search.html", "sidebar/home.html", "sidebar/navigation.html", "sidebar/ethical-ads.html", @@ -680,7 +680,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'] = 'Sage {}'.format(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' @@ -689,7 +689,7 @@ def add_page_context(app, pagename, templatename, context, doctree): if 'reference' in path1 and not path1.endswith('reference'): path2 = os.path.join(SAGE_DOC, 'html', 'en', 'reference') relpath = os.path.relpath(path2, path1) - context['reference_title'] = 'Sage {}'.format(release) + ' Reference Manual' + context['reference_title'] = f'Version {release} Reference Manual' context['reference_root'] = os.path.join(relpath, 'index.html') context['refsub'] = True if pagename.startswith('sage/'): From 4087242d36ae300f9aae07c501e7231ead17fc1e Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Tue, 2 Jul 2024 18:38:03 +0900 Subject: [PATCH 23/32] Insert develop version on the fly --- src/bin/sage-update-version | 2 +- src/doc/common/static/jupyter-sphinx-furo.js | 4 ++++ src/doc/en/website/versions.txt | 9 +++------ 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/bin/sage-update-version b/src/bin/sage-update-version index 7d735c12e6c..179461a8340 100755 --- a/src/bin/sage-update-version +++ b/src/bin/sage-update-version @@ -115,7 +115,7 @@ envsubst <"$SAGE_ROOT/CITATION.cff.in" >"$SAGE_ROOT/CITATION.cff" # Update src/doc/versions.txt file storing the URLs of the docs for the recent stable releases if [[ $SAGE_VERSION =~ ^[0-9]+(\.[0-9]+)*$ ]]; then file_path="$SAGE_ROOT/src/doc/en/website/versions.txt" - # Extract the most recent version line from versions.txt; the first line is a comment + # Extract the most recent version line from versions.txt line_number=$(grep -n '^[0-9]' "$file_path" | head -n 1 | cut -d: -f1) version_line=$(sed -n "${line_number}p" "$file_path") domain=${version_line#*--} diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index b086a5c27ea..b95159d20bb 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -99,6 +99,10 @@ async function fetchVersions() { } versionMap[current_version] = url + if (current_version != 'develop') { + versionMap['develop'] = "https://doc-develop--sagemath.netlify.app"; + } + // Parse the versions.txt file lines.forEach(line => { if (!line.startsWith('#')) { // Ignore the comment line diff --git a/src/doc/en/website/versions.txt b/src/doc/en/website/versions.txt index b963bcbd4ca..12aed2b8cfe 100644 --- a/src/doc/en/website/versions.txt +++ b/src/doc/en/website/versions.txt @@ -1,15 +1,12 @@ -# This file is used by the version selector of the sage doc +# This file is used by the version selector of the Sage doc # and updated by the script src/bin/sage-update-version -# run by the release manager to prepare a new release # -# The first line is reserved for develop version -# The other lines are for recent stable releases (at most 10 lines) +# The lines are for recent stable releases (at most 10 lines) # A line consists of the version and the URL to the doc # # 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 # -# Do not edit manually -dev doc-release--sagemath.netlify.app 10.4 doc-10-4--sagemath.netlify.app 10.3 doc-10-3--sagemath.netlify.app 10.2 doc-10-2--sagemath.netlify.app From 67729bef418587901c7e75d7f1596fc603699d16 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Tue, 2 Jul 2024 22:31:46 +0900 Subject: [PATCH 24/32] Backing up --- src/doc/common/static/custom-furo.css | 5 - src/doc/common/static/jupyter-sphinx-furo.js | 111 ++++++------------ .../sidebar/version-selector.html | 5 +- 3 files changed, 37 insertions(+), 84 deletions(-) diff --git a/src/doc/common/static/custom-furo.css b/src/doc/common/static/custom-furo.css index ba71d3d6b0f..ae304d2a15d 100644 --- a/src/doc/common/static/custom-furo.css +++ b/src/doc/common/static/custom-furo.css @@ -60,11 +60,6 @@ a.pdf:hover { text-align: center; } -.select-wrapper::before { - content: "switch to"; - font-size: small; -} - body[data-theme="dark"] { #versions-menu { background-color: black; diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index b95159d20bb..6a700cc5cbf 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -62,97 +62,52 @@ observer2.observe(document.getElementsByClassName("content")[0], { childList: tr // Version selector // -var versionMap = {}; - -async function fetchVersions() { +function fetchVersions() { try { - // For the origin of this site, see .github/workflows/doc-publish.yml - let versions_file = "https://doc-release--sagemath.netlify.app/html/en/versions.txt"; - let response = await fetch(versions_file); - if (!response.ok) { - throw new Error('Network response was not ok'); - } - let text = await response.text(); - let lines = text.split('\n'); - - let url = window.location.origin; - let current_version - - if (window.location.protocol == 'file:') { - current_version = 'local'; - url = window.location.href; - } else { - let start_index = url.indexOf('doc-') + 4; - let end_index = url.indexOf('--'); - let version_string = url.substring(start_index, end_index); - - // Consult the comment in .github/workflows/doc-publish.yml - if (/^pr-\d+$/.test(version_string)) { - current_version = version_string.replace(/-/g, ' '); - } else if (version_string === 'release') { - current_version = 'latest'; - } else if (version_string === 'develop') { - current_version = 'develop'; - } else { - current_version = version_string.replace(/-/g, '.'); - } - } - versionMap[current_version] = url - - if (current_version != 'develop') { - versionMap['develop'] = "https://doc-develop--sagemath.netlify.app"; - } + let menu = document.getElementById('versions-menu'); - // Parse the versions.txt file - lines.forEach(line => { - if (!line.startsWith('#')) { // Ignore the comment line - let [ver, url] = line.split(' '); - if (ver && url) { - if (!url.startsWith("https://")) { - url = "https://" + url; - } - versionMap[ver] = url; + // For the origin of the this site, see .github/workflows/doc-publish.yml + fetch('https://doc-release--sagemath-test.netlify.app/html/en/versions.txt') + .then(response => { + if (!response.ok) { + throw new Error('Network response was not ok ' + response.statusText); } - } - }); + return response.text(); + }) + .then(text => { + const lines = text.split('\n'); + lines.forEach(line => { + if (!line.startsWith('#')) { // Ignore the comment line + let [ver, url] = line.split(' '); + if (ver && url) { + if (!url.startsWith('https://')) { + url = 'https://' + url; + } + let option = document.createElement('option'); + option.value = url; + option.text = ver; + menu.add(option); + } + } + }); + }); } catch (error) { console.error("Failed to fetch versions.txt file:", error); } - - let menu = document.getElementById("versions-menu"); - - if (Object.keys(versionMap).length > 0) { - Object.keys(versionMap).forEach(ver => { - let option = document.createElement("option"); - option.value = ver; - option.text = ver; - menu.add(option); - }); - } else { - menu.style.display = 'none'; - } - - let urlParams = new URLSearchParams(window.location.search); - let version = urlParams.get("ver"); - // Check if the version exists in the map and redirect - if (version && version in versionMap) { - let targetUrl = versionMap[version]; - window.location.href = targetUrl + window.location.pathname; - } } fetchVersions() // Function to change the version based on versions menu selection function changeVersion() { - let selected_version = document.getElementById("versions-menu").value; - if (selected_version) { - // Check if the version exists in the map and redirect - if (selected_version in versionMap) { - let targetUrl = versionMap[selected_version]; - window.location.href = targetUrl + window.location.pathname; + let select_element = document.getElementById("versions-menu"); + let selected_ver = select_element.options[select_element.selectedIndex].text; + let selected_url = select_element.value; + if (selected_url) { + if (window.location.protocol == 'file:') { + window.location.href = selected_url + 'html/en/index.html'; } else { - console.error("Version not found in versions.txt."); + window.location.href = selected_url + window.location.pathname; } } } diff --git a/src/doc/common/templates-furo/sidebar/version-selector.html b/src/doc/common/templates-furo/sidebar/version-selector.html index bd18e666d88..6807b131dcf 100644 --- a/src/doc/common/templates-furo/sidebar/version-selector.html +++ b/src/doc/common/templates-furo/sidebar/version-selector.html @@ -1,3 +1,6 @@
- +
From 02fcfe401251b346e9a1dfa014a323e530cfb1a1 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Tue, 2 Jul 2024 23:39:34 +0900 Subject: [PATCH 25/32] Fix css --- src/doc/common/static/custom-furo.css | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/doc/common/static/custom-furo.css b/src/doc/common/static/custom-furo.css index ae304d2a15d..85d2a0776cf 100644 --- a/src/doc/common/static/custom-furo.css +++ b/src/doc/common/static/custom-furo.css @@ -42,6 +42,11 @@ a.pdf:hover { z-index: 100; } +.select-wrapper { + display: block; + text-align: center; +} + #versions-menu { display: inline-block; font-size: small; @@ -55,21 +60,16 @@ a.pdf:hover { outline: none; } -.select-wrapper { - display: block; - text-align: center; -} - body[data-theme="dark"] { #versions-menu { - background-color: black; + background-color: transparent; } } @media (prefers-color-scheme: dark) { body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */ #versions-menu { - background-color: black; + background-color: transparent; } } } From e9d58da9f5ad5214f8c311a3eccc99b3788c3594 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Tue, 2 Jul 2024 23:48:43 +0900 Subject: [PATCH 26/32] Fix doc-release url --- src/doc/common/static/jupyter-sphinx-furo.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 6a700cc5cbf..95a568dacbb 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -67,7 +67,7 @@ function fetchVersions() { let menu = document.getElementById('versions-menu'); // For the origin of the this site, see .github/workflows/doc-publish.yml - fetch('https://doc-release--sagemath-test.netlify.app/html/en/versions.txt') + fetch('https://doc-release--sagemath.netlify.app/html/en/versions.txt') .then(response => { if (!response.ok) { throw new Error('Network response was not ok ' + response.statusText); From e01bc4e55da3c6c50d38d9be16d05cc57b69a40b Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Wed, 3 Jul 2024 00:21:21 +0900 Subject: [PATCH 27/32] Squeeze fetch-related error --- src/doc/common/static/jupyter-sphinx-furo.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index 95a568dacbb..a11aa04f8a3 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -90,9 +90,12 @@ function fetchVersions() { } } }); + }) + .catch(error => { + console.log('Failed to fetch versions.txt file.'); }); } catch (error) { - console.error("Failed to fetch versions.txt file:", error); + console.log('Failed to fetch versions.txt file.'); } } From ed0c21ebdbc28968de2b2631c29c81fc623c87ad Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Wed, 3 Jul 2024 08:26:15 +0900 Subject: [PATCH 28/32] Improve version selector for local doc --- src/doc/common/static/jupyter-sphinx-furo.js | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index a11aa04f8a3..b63de354db8 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -108,7 +108,14 @@ function changeVersion() { let selected_url = select_element.value; if (selected_url) { if (window.location.protocol == 'file:') { - window.location.href = selected_url + 'html/en/index.html'; + let pathname = window.location.pathname; + let cutoff_point = pathname.indexOf('doc/sage'); + if (cutoff_point !== -1) { + pathname = pathname.substring(cutoff_point + 8); + window.location.href = selected_url + pathname; + } else { + window.location.href = selected_url + 'html/en/index.html'; + } } else { window.location.href = selected_url + window.location.pathname; } From a9decf4a57a11c723e38ce0dd8cdc28485fac98d Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Wed, 3 Jul 2024 10:35:18 +0900 Subject: [PATCH 29/32] 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 30/32] 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 31/32] 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 32/32] 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'