Upload documentation tarballs to GitHub releases

[c8ef]

Add pre-built HTML and PDF documentation uploads to the release workflow. When triggered by a tag push, the workflow now creates and uploads livedoc.zip to the corresponding GitHub release.

My tests:

• https://github.com/mango-mice/sage/actions/runs/21561917179/job/62127753072
• https://github.com/mango-mice/sage/releases
• https://github.com/mango-mice/sage/releases/download/10.9.beta99/livedoc.zip

Closes #39949.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

[c8ef]

cc @gmou3

[gmou3]

Thanks for the PR. I am not very confident approving this, so I will leave it to others.

This is supposed to close #39949.

[c8ef]

Thanks for the PR. I am not very confident approving this, so I will leave it to others.

This is supposed to close #39949.

Thank you for the initial review! I linked the issue here.

[kwankyu]

I fear that the step may run before the release is made. According to AI,

      - name: Check if release exists
        id: check_release
        run: |
          if gh release view ${{ github.ref_name }} > /dev/null 2>&1; then
            echo "exists=true" >> $GITHUB_OUTPUT
          else
            echo "exists=false" >> $GITHUB_OUTPUT
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload docs to release
        uses: softprops/action-gh-release@v2
        if: steps.check_release.outputs.exists == 'true'
        with:
          files: livedoc.zip
          token: ${{ secrets.RELEASE_CREATION_TOKEN }}
        if: github.ref_type == 'tag'

will check if a release for the tag exists before uploading assets.

[c8ef]

I fear that the step may run before the release is made. According to AI,

      - name: Check if release exists
        id: check_release
        run: |
          if gh release view ${{ github.ref_name }} > /dev/null 2>&1; then
            echo "exists=true" >> $GITHUB_OUTPUT
          else
            echo "exists=false" >> $GITHUB_OUTPUT
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload docs to release
        uses: softprops/action-gh-release@v2
        if: steps.check_release.outputs.exists == 'true'
        with:
          files: livedoc.zip
          token: ${{ secrets.RELEASE_CREATION_TOKEN }}
        if: github.ref_type == 'tag'

will check if a release for the tag exists before uploading assets.

I initially had the same concerns, but after looking into it, I realized my current implementation is actually sufficient.

The softprops/action-gh-release@v2 action ensures that there is only one release per tag. Regardless of which action finishes first, any subsequent actions triggered for that same tag will simply append their assets to the existing release. Because of this, whether the documentation or the wheels finish first, everything consolidates into a single release - which is exactly what we want.

Practically speaking, building the docs takes much longer than building the wheels, so the wheels will almost certainly be uploaded first anyway.

[kwankyu]

The softprops/action-gh-release@v2 action ensures that there is only one release per tag. Regardless of which action finishes first, any subsequent actions triggered for that same tag will simply append their assets to the existing release. Because of this, whether the documentation or the wheels finish first, everything consolidates into a single release - which is exactly what we want.

Unfortunately, the release script often fails to work as expected. See https://github.com/sagemath/sage/actions/workflows/release.yml

When that happens, your step will create a new release with only asset livedoc.zip. I think this is not desirable.

[github-actions]

Documentation preview for this PR (built with commit 1f1890c; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[c8ef]

The softprops/action-gh-release@v2 action ensures that there is only one release per tag. Regardless of which action finishes first, any subsequent actions triggered for that same tag will simply append their assets to the existing release. Because of this, whether the documentation or the wheels finish first, everything consolidates into a single release - which is exactly what we want.

Unfortunately, the release script often fails to work as expected. See https://github.com/sagemath/sage/actions/workflows/release.yml

When that happens, your step will create a new release with only asset livedoc.zip. I think this is not desirable.

While not perfect, it can achieve a form of eventual consistency. If we check the release status during the document build action, the release action may fail while the document build action succeeds but does not upload the asset.

Therefore, I suggest merging the livedoc action into the release action, as they share the same trigger condition. WDYT? @kwankyu

[c8ef]

Also found a small bug in the release yml, opened #41669 to fix it.

[kwankyu]

.. If we check the release status during the document build action, the release action may fail ...

Why do you think so?

Therefore, I suggest merging the livedoc action into the release action, as they share the same trigger condition.

That seems a bulky solution. Those are conceptually separate workflows.

[c8ef]

.. If we check the release status during the document build action, the release action may fail ...

Why do you think so?

As I understand it, retrying the release action will not automatically trigger the doc build. So if the release fails but the doc build succeeds, retrying the release will result in the release artifact being published without the live docs included.

[c8ef]

Therefore, I suggest merging the livedoc action into the release action, as they share the same trigger condition.

That seems a bulky solution. Those are conceptually separate workflows.

Maybe we can transform the doc build workflow to use a workflow_call trigger, so it can be called as part of the release action?

[kwankyu]

As I understand it, retrying the release action will not automatically trigger the doc build. So if the release fails but the doc build succeeds, retrying the release will result in the release artifact being published without the live docs included.

Right. But in that case, we can manually drop the artifact livedoc.zip as an asset to the release.

[kwankyu]

Maybe we can transform the doc build workflow to use a workflow_call trigger, so it can be called as part of the release action?

That may be another complicated solution, which builds the doc twice.

If the release workflow fails, a release should be created manually anyway. Your original solution at least provides a release with livedoc.zip asset. So now your original solution seems to be the best.

I am okay with merging this PR now and we may see how it goes with the next stable release.

[gmou3]

Isn't livedoc.zip a somewhat cryptic name?

I would expect a name like sagemath-{version}-documentation.zip.

Note that the list of assets of a release is large, so people will probably search for documentation with Ctrl+f.

[kwankyu]

Let me summarize what happened with 10.9.beta7 release:

https://github.com/sagemath/sage/actions/runs/22418172347

https://github.com/sagemath/sage/actions/runs/22418172388/job/64909125824

Somehow a draft of the release 10.9.beta7 was created anyway with no livedoc.zip asset. I manually edited the draft and published it as a prerelease (with the already uploaded assets) : https://github.com/sagemath/sage/releases

[c8ef]

Let me summarize what happened with 10.9.beta7 release:

https://github.com/sagemath/sage/actions/runs/22418172347

https://github.com/sagemath/sage/actions/runs/22418172388/job/64909125824 Somehow a draft of the release 10.9.beta7 was created anyway with no `livedoc.zip` asset. I manually edited the draft and published it as a prerelease (with the already uploaded assets) : https://github.com/sagemath/sage/releases

I encountered a rate limiter for the release action in my own fork once. I haven't encountered the latter one yet. Maybe this is a temporary issue with GitHub?