Restore support for SAGE_DOCBUILD_OPTS

[orlitzky]

In the past, SAGE_DOCBUILD_OPTS was included on the command-line in most scenarios where the documentation build was invoked. At some point, this got lost. In an ideal future it will no longer be necessary, but right now, supporting it makes it easy for the CI to include TESTS blocks in the documentation.

In the docbuild's main(), we now prepend SAGE_DOCBUILD_OPTS to sys.argv[1:] before calling parse_args(). To convert the variable (a string) to a list, we split on whitespace. This isn't great, but it gets the job done in typical use cases. The "easy" way to accomplish this goal would be to insert SAGE_DOCBUILD_OPTS into the docbuild command in src/doc/meson.build, but the meson people feel rather strongly that you shouldn't be able to access environment variables within the build.

Closes: #41609

The main issue (for me) that this solves is the absence of the TESTS blocks in the documentation previews. A random documentation page where TESTS are visible:

• https://doc-pr-41776--sagemath.netlify.app/html/en/reference/quat_algebras/sage/algebras/quatalg/quaternion_algebra

And its counterpart in another open PR, with no TESTS:

• https://doc-pr-41768--sagemath.netlify.app/html/en/reference/quat_algebras/sage/algebras/quatalg/quaternion_algebra

[github-actions]

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

[orlitzky]

@kwankyu this fixes some aspects of the documentation preview that I remember you working on.

[kwankyu]

FYI, the variable is documented here:

https://doc-10-7--sagemath.netlify.app/html/en/installation/source.html#envvar-SAGE_DOCBUILD_OPTS

and as of Sage 10.6, it is found at:

sage-10.6$ rg "SAGE_DOCBUILD_OPTS"
.github/workflows/doc-build.yml
196:          export SAGE_DOCBUILD_OPTS="--include-tests-blocks"

build/make/Makefile.in
381:	+$(MAKE_REC) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-plot" doc-html

src/doc/Makefile
28:	sage --docbuild --no-pdf-links $(subst -,/,$(subst doc-inventory--,,$@)) inventory $(SAGE_DOCBUILD_OPTS)
32:	sage --docbuild --no-pdf-links $(subst -,/,$(subst doc-html--,,$@)) html $(SAGE_DOCBUILD_OPTS)
46:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-inventory--reference_top
55:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-html--$(subst /,-,$(BIBLIO))
56:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(OTHER_DOCS), doc-html--$(subst /,-,$(doc)))
60:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-html--reference_top
72:	LATEXOPTS="--file-line-error --interaction=batchmode" sage --docbuild $(subst -,/,$(subst doc-pdf--,,$@)) pdf $(SAGE_DOCBUILD_OPTS)
80:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-pdf--$(subst /,-,$(BIBLIO))
81:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(OTHER_DOCS), doc-pdf--$(subst /,-,$(doc)))
82:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-pdf--reference_top
88:	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(wordlist 2, 100, $(DOCS)), doc-pdf--$(subst /,-,$(doc)))

src/doc/en/installation/source.rst
637:  ``export SAGE_DOCBUILD_OPTS+=' --no-plot'``
966:.. envvar:: SAGE_DOCBUILD_OPTS

In general, I prefer reviving make doc-html in CI. Note that it was replaced with meson build, that, in particular, does not work for "live doc" (interactive Examples) currently.

[orlitzky]

In general, I prefer reviving make doc-html in CI. Note that it was replaced with meson build, that, in particular, does not work for "live doc" (interactive Examples) currently.

We could fix the CI with this approach, but the sagelib build system (which builds the docs once itself) doesn't use the Makefile or the "sage" script, so the documentation for SAGE_DOCBUILD_OPTS would still be misleading to end users.

[kwankyu]

Don't you need to edit the lines here? https://doc-10-8--sagemath.netlify.app/html/en/installation/source-distro.html#envvar-SAGE_DOCBUILD_OPTS

[orlitzky]

Don't you need to edit the lines here? https://doc-10-8--sagemath.netlify.app/html/en/installation/source-distro.html#envvar-SAGE_DOCBUILD_OPTS

The title of this page is "Sage-the-distribution (classical build)", and in that context this section is still accurate. Running make doc will eventually provoke meson to run src/build-docs.py, which then runs src/sage_docbuild/__main__.py. This is also what sage --docbuild does, so modulo some implementation details we are not lying about how SAGE_DOCBUILD_OPTS is used in sage-the-distribution.

[kwankyu]

This line

The value of this variable is passed as an argument to sage --docbuild all html or sage --docbuild all pdf when you run make, make doc, or make doc-pdf.

is not correct any more. How about this?

The value of this variable is passed to the Sage doc builder when you run make doc, make doc-html or make doc-pdf.

On the other hand sage --docbuild has been broken...

[orlitzky]

No problem, I have tried to clarify that line without getting into specifics. Instead of sage --docbuild --help (which does not work without messing with PYTHONPATH), I have pointed everyone to the header of the relevant source file.

[kwankyu]

Thanks.