Use doc-develop artifact and include TESTS in doc preview for PRs

[kwankyu]

trafficstars

We include TESTS blocks in development documentation, so that they are visible at least during development. Then not to ruin CHANGES.html, we refactor doc build github workflow. The idea is to upload artifact doc-develop so that doc diffs are computed against the doc contained in the artifact.

test: https://doc-develop--sagemath-test.netlify.app/html/en/reference/structure/sage/structure/sage_object Look around to fine new "TESTS" blocks.

test - doc-develop artifact: https://github.com/kwankyu/sage/actions/runs/10786441764

We also remove all spurious diffs caused by EXAMPLES tabs indices change. Tests for PR event.

test - doc build workflow run: https://github.com/kwankyu/sage/actions/runs/10786483761/job/29913420105

test - CHANGES.html: https://doc-pr-64--sagemath-test.netlify.app/changes Here note that

• diffs in EXAMPLES block show twice once for sage tab and once again for python tab. This is unavoidable.
• The spurious eternal diff shown in https://doc-pr-38468--sagemath.netlify.app/changes is gone forever.

Note that doc build for this PR itself fails here, of course. We may ignore this.

The commit 4d05601 is to mitigate "out of disk space" failure, seen in https://github.com/sagemath/sage/actions/runs/10691572586.

test: https://github.com/kwankyu/sage/actions/runs/10786477715

:memo: Checklist

• [x] The title is concise and informative.
• [x] The description explains in detail what this PR is about.
• [x] 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.

:hourglass: Dependencies

#38468

[github-actions[bot]]

Documentation preview for this PR (built with commit 3162bc85bd1a73eb886b1c37e4695c5f4761ffd9; changes) is ready! :tada: This preview will update shortly after each push to this PR.

[mkoeppe]

And we include TESTS blocks in development documentation, so that they are visible at least during development.

Interesting idea. Do you have plans beyond this for the TESTS blocks?

[kwankyu]

And we include TESTS blocks in development documentation, so that they are visible at least during development.

Interesting idea. Do you have plans beyond this for the TESTS blocks?

No. Actually while investigating the cause of the hunk 1 in https://doc-pr-38468--sagemath.netlify.app/changes, I have now realized that this PR won't work as I expected, at least with the current infrastructure.

When we compute diffs to create CHANGES.html, we compare the "new" doc for the PR with the "old" doc built by CI Linux workflow for the develop branch. The "old" doc was built with parsed examples and no TESTS. We should not change this. For reasonable diffs, the "new" doc should not deviate from this mode.

One way to escape the dilemma is to get the "old" doc from the artifact produced by doc-build workflow run for develop branch. I don't know if this is doable or desirable...

~~I may close this PR for now.~~

[kwankyu]

I did necessary refactoring to implement this PR. Now doc build for pull request event downloads doc-develop artifact to compute diffs to create CHANGES.html.

[kwankyu]

One way to escape the dilemma is to get the "old" doc from the artifact produced by doc-build workflow run for develop branch. I don't know if this is doable or desirable...

Done.

[kwankyu]

@mkoeppe I think this PR is now tasty.

[kwankyu]

The last commit is to mitigate the "out of disk space" failure.

[dimpase]

build-doc CI step is failing, as you introduced new "target" doc-develop.

Is there a way to fix this?

[kwankyu]

It is expected, and cannot be "fixed" here. The artifact doc-develop will be generated at next beta release after merging this pr.

If you want to see a test result, I will prepare one in my repo. Wait some minutes.

[kwankyu]

doc-build for a dummy PR for testing is running here:

https://github.com/kwankyu/sage/actions/runs/11789320959/job/32837887930

[kwankyu]

Thanks!