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

actually what is livedoc release? I mostly just use the Documentation preview link for development which still works… I think.

and what rule determines which user can deploy to which netlify URL?

actually what is livedoc release? I mostly just use the Documentation preview link for development which still works… I think.

See the updated PR description. The doc-release is published on every release (so about weekly).

and what rule determines which user can deploy to which netlify URL?

No user deploys. The netlify URL is determined by the sage repo secrets NETLIFY_SITE_ID and NETLIFY_AUTH_TOKEN which currently points to my netlify site.

You can add "Fixes #40463" to the PR description.

Thanks. A test running at my repo is not yet finished; hence "Draft" state yet.

Is there a published version of the built PDF documentation accessible somewhere? I can't find it.

The test is building pdfs. I will show you when it finished.

I assume meson builds things faster than make (but doc-build is not 100% meson either, it still uses bootstrap at some parts), it's unfortunate that meson live doc doesn't work. If I understood correctly the logic is moved to doc-build-pdf just because doc-build-pdf still uses make (while doc-build uses meson).

Still, working slow code is better than broken code.

(also, any idea which part of the code is responsible for deploying the documentation preview on each pull request, and why does that one actually work?)

I assume meson builds things faster than make (but doc-build is not 100% meson either, it still uses bootstrap at some parts), it's unfortunate that meson live doc doesn't work.

It does work. But doc-release (=live doc + pdf docs) needs pdf docs, for which meson does not work yet (right?).

If I understood correctly the logic is moved to doc-build-pdf just because doc-build-pdf still uses make (while doc-build uses meson).

Yes.

Still, working slow code is better than broken code.

For once a weak release, "slow" does not matter much.

(also, any idea which part of the code is responsible for deploying the documentation preview on each pull request, and why does that one actually work?)

See doc-publish.yml

But doc-release (=live doc + pdf docs) needs pdf docs, for which meson does not work yet (right?).

not really. sage --docbuild en/tutorial pdf works just fine in meson, provided you install the sage_docbuild package into the Python environment first. So is sage --docbuild reference/stats pdf.

sage --docbuild en/reference pdf, however, is currently broken… (with or without the en)

It does work.

I assume the original # The following fails randomly comments (that you deleted) means that it does not work. I haven't checked what's the error.

Thanks for fixing this!

A few initial questions/comments:

• What's the reason for moving the livedocs to the pdf run? They are just a different 'flavor' of the html build, right? Perhaps it's easier to just move the pdf build to the html (as a separate job) and then rename the workflow simply to "doc build".
• I would prefer if it uses meson directly, if that's now working.
• The released html seems to have broken styles, eg https://doc-release--sagemath.netlify.app/html/en/reference/rings_standard/ doesn't render nicely for me.
• Could you please also add this "doc-release" url somewhere in the documentation and readme, so that it's easier to find.

• What's the reason for moving the livedocs to the pdf run? They are just a different 'flavor' of the html build, right? Perhaps it's easier to just move the pdf build to the html (as a separate job) and then rename the workflow simply to "doc build".
• I would prefer if it uses meson directly, if that's now working.

I think this is already discussed above: none of us knows why livedoc on meson fails (yet), so a temporary workaround is to use it in the pdf, which is still based on make.

• The released html seems to have broken styles, eg https://doc-release--sagemath.netlify.app/html/en/reference/rings_standard/ doesn't render nicely for me.

probably just a mistake caused while doing the manual upload, if you change the sagemath to sagemath-test (automated upload) then it works well. In any case I don't see it as an evidence of the code being incorrect.

• Could you please also add this "doc-release" url somewhere in the documentation and readme, so that it's easier to find.

As mentioned in the first message, it's linked from the wiki. I agree it's hard to find though, having in the README would be good.

The README, however, links to https://doc.sagemath.org/html/en/index.html—which makes sense, since this is user-facing, and unreleased versions are not visible to most users. Maybe https://doc.sagemath.org/html/en/developer/index.html#section-updating-documentation would be suitable.

It does work.

I assume the original # The following fails randomly comments (that you deleted) means that it does not work. I haven't checked what's the error.

It works with "-j1", as you suggested as a fix.

Okay, so currently we have meson builds HTML doc, and make builds PDF doc.

Why do we need to build the HTML again in the "Build live doc" step, if meson can already build HTML with -j1 workaround?

• I would prefer if it uses meson directly, if that's now working.

I think this is already discussed above: none of us knows why livedoc on meson fails (yet), so a temporary workaround is to use it in the pdf, which is still based on make.

Right. Later if everything works well with meson, all could be combined into single "doc-build.yml" and "doc-publish.yml". However, since building pdf docs takes more time, having separate workflows might be still preferred.

• The released html seems to have broken styles, eg https://doc-release--sagemath.netlify.app/html/en/reference/rings_standard/ doesn't render nicely for me.

probably just a mistake caused while doing the manual upload, if you change the sagemath to sagemath-test (automated upload) then it works well. In any case I don't see it as an evidence of the code being incorrect.

Correct.

• Could you please also add this "doc-release" url somewhere in the documentation and readme, so that it's easier to find.

As mentioned in the first message, it's linked from the wiki. I agree it's hard to find though, having in the README would be good.

The README, however, links to https://doc.sagemath.org/html/en/index.html—which makes sense, since this is user-facing, and unreleased versions are not visible to most users.

Right. "doc-release" is for developers. That provides a sample to be eventually released for users.

On the other hand, https://doc.sagemath.org provides the official doc for stable releases for ordinary users. I hope that that also provides live doc...

Maybe https://doc.sagemath.org/html/en/developer/index.html#section-updating-documentation would be suitable.

I looked around. But I don't see a suitable place; the section is focused on local development.

Perhaps Wiki itself should be advertised, but isn't it wildly visible?

For your information, "doc-release" is also essential for "other version" selector (see below the Sage logo on the left panel) to work. It is currently broken.

"doc-release" is the source of "other versions" info. See https://doc-release--sagemath.netlify.app/html/en/versions.txt

I updated the Wiki to emphasize the doc-release.

Why do we need to build the HTML again in the "Build live doc" step, if meson can already build HTML with -j1 workaround?

"again" because it is "live doc". And in doc-build-pdf because doc-release should contain pdf docs.

An alternative approach is to build live doc with '-j1' in "doc-build" and publish doc-release with pdf docs built in "doc-build-pdf" (after wasting time waiting for pdf docs) But this approach would slow down doc previews for PRs.

"again" because it is "live doc"

Just to clarify, the point is the Sage Live tab on the documentation page right?

I've actually never heard of the feature before. It needs more advertisement, I suppose.

Perhaps Wiki itself should be advertised, but isn't it wildly visible?

I've never heard of the wiki before either.

I think one useful place to introduce it is in the message by github-actions itself. Currently it says

            [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.

we could add a

This message is automatically generated by <something>.
Refer to https://doc.sagemath.org/html/en/developer/[...] for an explanation how it works.

An alternative approach is to build live doc with '-j1' in "doc-build" and publish doc-release with pdf docs built in "doc-build-pdf" (after wasting time waiting for pdf docs) But this approach would slow down doc previews for PRs.

I like this approach better. The live docs are only build on releases and take quite some time, right? So in this case, it would be okay to wait for the live docs + pdf build before publishing them together.

Btw, what is the difference between the doc-release and doc-develop netlify sites?

I would be fine changing the first sentence on https://doc-develop--sagemath.netlify.app/html/en/index.html to "Documentations in other languages and the most recent beta release are available too." and then link the doc-release. And a similar sentence can be added in the readme.

For your info, in #40597, I've now fixed the pdf-meson build and migrated the CI to it.

I've actually never heard of the feature before. It needs more advertisement, I suppose.

It was first advertised here: https://github.com/sagemath/sage/wiki/Sage-10.2-Release-Tour#documentation

... we could add a

This message is automatically generated by <something>.
Refer to https://doc.sagemath.org/html/en/developer/[...] for an explanation how it works.

I guess we are talking about doc-release and live doc; this thing is different from doc previews for PRs.

I think we may add a subsection about the automatic generation of various docs for developers available in github interface (perhaps also about the Wiki :-) in the section about the github repo: https://doc-release--sagemath.netlify.app/html/en/developer/github# However, then this issue is somewhat beyond the present PR. I may do this work in a new PR.

An alternative approach is to build live doc with '-j1' in "doc-build" and publish doc-release with pdf docs built in "doc-build-pdf" (after wasting time waiting for pdf docs) But this approach would slow down doc previews for PRs.

I like this approach better. The live docs are only build on releases and take quite some time, right? So in this case, it would be okay to wait for the live docs + pdf build before publishing them together.

I gave up that approach and took the present approach, because that approach would slow down generation of doc previews for PRs since the doc-publish action needs to wait for the completion of building pdf docs, which takes long.

Btw, what is the difference between the doc-release and doc-develop netlify sites?

doc-develop is used when doc preview diffs (changes) for a PR is generated, by comparing it with doc-pr-xxxxx.

I would be fine changing the first sentence on https://doc-develop--sagemath.netlify.app/html/en/index.html to "Documentations in other languages and the most recent beta release are available too." and then link the doc-release. And a similar sentence can be added in the readme.

I don't agree. That sentence is about the specific doc version. It is inappropriate to talk about other versions in the same sentence.

Anyway, let's deal with the advertisement issue in a new PR mentioned in the previous comment.

For your info, in #40597, I've now fixed the pdf-meson build and migrated the CI to it.

I don't know meson and how things are going about meson transition. Hopefully in a sequel to this PR, you may convert pdf doc build stuffs to meson and perhaps then merge doc-build.yml and doc-build-pdf.yml (or not because of the delayed doc previews issue). Let's get this in for now.

Sure, I'm all in favor of this. I would propose to simply call uv sync to setup the python venv. Then you can reduce sage-the-distro to non-python only dependencies.

b81df17 merely upgrades a bunch of packages. Which of them causes the regression? setuptools ?

I believe it may be setuptools. Other packages seem irrelevant

I am out of town. My branch needs some cleanup before shipping out. Sorry that the PR is delayed.

I am out of town. My branch needs some cleanup before shipping out. Sorry that the PR is delayed.

instead of reverting anything, applying #40633 gives me everything (beside doc-pdf, but that's a different story) working

instead of reverting anything, applying #40633 gives me everything (beside doc-pdf, but that's a different story) working

OK. I am testing at https://github.com/kwankyu/sage/actions/runs/17183907741

How do you access the pdf docs from the html pages? I don't see any reference to them in the link you shared above.

https://doc-release--sagemath.netlify.app/html/en/ (or click "here" in "...available here")
They were there for some years...

Oh thanks. I was looking for them further down in the docs.

But either way: this means this is nothing special for the live docs and that the pdf docs should be there for both the "doc-release" and "doc-develop" builds, right?

No pdf docs in "doc-develop". "doc-develop" for a release is there to make a doc preview for a PR and diffs of the doc preview against "doc-develop".

My proposal would be the following.

• For PRs:

  - html build   -->  doc-publish
  - pdf bulid
  

non-live "html build". Waiting for "pdf build" here will slow down doc previews for PRs.

This is the same as the current setup. Nothing is waiting for the pdf build.

I see. I misread your diagram.

instead of reverting anything, applying #40633 gives me everything (beside doc-pdf, but that's a different story) working

OK. I am testing at https://github.com/kwankyu/sage/actions/runs/17183907741

Hmm. I misunderstood you. #40633 does not solve the "sagemath" kernel problem, which is the main concern here. Right?

(I interpreted "beside" as "in addition to"...)

I will revert setuptools and setuptools_scm upgrade in b81df17, and test again.

instead of reverting anything, applying #40633 gives me everything (beside doc-pdf, but that's a different story) working

OK. I am testing at https://github.com/kwankyu/sage/actions/runs/17183907741

Hmm. I misunderstood you. #40633 does not solve the "sagemath" kernel problem, which is the main concern here. Right?

#40633 introduces a new problem regarding doc-pdf. That is probably what you meant by "that's a different story".

So I drop dependency on #40633.

Regarding the problematic commit b81df17, I revert only "setuptools" upgrades.

How do you access the pdf docs from the html pages? I don't see any reference to them in the link you shared above.

https://doc-release--sagemath.netlify.app/html/en/ (or click "here" in "...available here")
They were there for some years...

Oh thanks. I was looking for them further down in the docs.
But either way: this means this is nothing special for the live docs and that the pdf docs should be there for both the "doc-release" and "doc-develop" builds, right?

No pdf docs in "doc-develop". "doc-develop" for a release is there to make a doc preview for a PR and diffs of the doc preview against "doc-develop".

doc-develop is what is linked in the version selector of the officially published docs, so it's very much the canonical build of the develop branch.

No pdf docs in "doc-develop". "doc-develop" for a release is there to make a doc preview for a PR and diffs of the doc preview against "doc-develop".

doc-develop is what is linked in the version selector of the officially published docs,

The version selector is mainly intended to list stable releases. The develop branch was added for developers, in addition. (I know because I implemented the version selector and I am maintaining it.)

Currently the stable versions do not appear there because "doc-release" is broken.

so it's very much the canonical build of the develop branch.

Yes.

I understand that the purposes of doc-develop and doc-release are not clear and confusing because there is no documentation besides the few lines in the workflow files.

In the last commit, I tried to clean up the confusion. I will add more documentation to our developer manual later.

The branch was tested and works well. The "sagemath" kernel is now installed.

Please review, hopefully before the next release.

So it's a bug that https://doc-develop--sagemath.netlify.app/pdf/en/a_tour_of_sage/a_tour_of_sage.pdf is not working, right?

Things I like to see improved:

• Don't mix html and pdf building. Above it was cited that the reason for this is the usage of make in the pdf workflow. But you can use make also in the html workflow.
• Don't use make. This is going to be replaced by meson in the next couple of weeks, so will fail very soon again. (But if you insist of using make for now, that's fine with me.) I'm very happy to help with the meson-side of things.
• Publish the pdf's also on doc-develop so that the above url works. (This should be easy if you fix the first point, but it's not a hard requirement for me to get this merged)

So it's a bug that https://doc-develop--sagemath.netlify.app/pdf/en/a_tour_of_sage/a_tour_of_sage.pdf is not working, right?

No. It is a bug that pdf icons appear in doc-develop.

Things I like to see improved:

• Don't mix html and pdf building. Above it was cited that the reason for this is the usage of make in the pdf workflow. But you can use make also in the html workflow.
• Don't use make. This is going to be replaced by meson in the next couple of weeks, so will fail very soon again. (But if you insist of using make for now, that's fine with me.) I'm very happy to help with the meson-side of things.

meson or make is not my concern. If you want these "improvements", you open your own PR and work on it.

• Publish the pdf's also on doc-develop so that the above url works. (This should be easy if you fix the first point, but it's not a hard requirement for me to get this merged)

This is not an improvement. doc-develop is not intended to include pdfs. As I said above, its purpose is to be used for making "changes" (diffs) for PR doc previews.

instead of reverting anything, applying #40633 gives me everything (beside doc-pdf, but that's a different story) working

OK. I am testing at https://github.com/kwankyu/sage/actions/runs/17183907741

Hmm. I misunderstood you. #40633 does not solve the "sagemath" kernel problem, which is the main concern here. Right?

(I interpreted "beside" as "in addition to"...)

for me there is no sagemath kernel problem with #40633 as long as building the usual docs is concerned.

Please explain how your sagemath kernel problem differs from this one.

By "besides" I meant the issue of using an external jupyter installation - this is broken for me, and has been the case for long time

the core reason for #40633 and all the related shenanigans is our manual handling of Python dependency resolution, something which I have been protesting about for years, yet it has been crammed into Sage with all these version_requirements.txt etc. Instead of the normal Pythonic pip install sphinx etc.

Now we witness an entirely predictable fallout from this.

Sorry, I digressed.

At least for me with the upgraded setuptools of b81df17, even though the doc appeared as built, looking at the logs, tutorial was not built because no sagemath jupyter kernel existed. With the previous setuptools, it is OK. Moreover with the upgraded setuptools calling make rebuilt completely always.

for me there is no sagemath kernel problem with #40633 as long as building the usual docs is concerned.

The branch of #40633 merged to my branch failed in building Pillow.

The branch of #40633 alone was built with no sagemath kernel installed. (I will try this again for #40633)

Then I gave up. (They are on my mac.)

The branch of #40633 alone was built with no sagemath kernel installed. (I will try this again for #40633)

Built after make distclean:

$ ./sage -sh

Starting subshell with Sage environment variables set.  Don't forget
to exit when you are done.  Beware:
 * Do not do anything with other copies of Sage on your system.
 * Do not use this for installing Sage packages using "sage -i" or for
   running "make" at Sage's root directory.  These should be done
   outside the Sage shell.

Bypassing shell configuration files...

Note: SAGE_ROOT=/Users/kwankyu/GitHub/sage-temp
(sage-sh) $ jupyter kernelspec list
Available kernels:
  python3    /Users/kwankyu/GitHub/sage-temp/local/var/lib/sage/venv-python3.13/share/jupyter/kernels/python3

no "sagemath" kernel.