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 +166,44 @@ 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 '/ { - 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: Extract docs - run: unzip docs.zip -d docs && unzip docs/docs.zip -d docs/docs + 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 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 + # 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: @@ -74,10 +79,10 @@ 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 - if: ${{ always() }} env: DEPLOY_SUCCESS: Successfully deployed preview. DEPLOY_FAILURE: Failed to deploy preview. @@ -88,50 +93,64 @@ 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 - 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 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 - 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 + - name: Deploy to netlify with doc-TAG alias 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: doc-${{ steps.source-run-info.outputs.targetBranch }} + 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 }} - NETLIFY_MESSAGE: Deployed live doc - NETLIFY_ALIAS: livedoc + 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 }}" + if: steps.download-doc.outcome == 'success' 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{%