"sage --docbuild DOC html" is broken

[jhpalmieri]

If I do make doc-clean && make doc and then for example sage --docbuild tutorial html, first it successfully builds the html tutorial, but then it fails because it tries to build the PDF documentation. I also don't know where it is building the PDF docs, because local/share/docs/sage/latex does not exist.

% ./sage --docbuild tutorial html  
[tutorial ] building [html]: targets for 23 source files that are out of date
[tutorial ] updating environment: [extensions changed ('2')] 23 added, 0 changed, 0 removed
[tutorial ] Merging environment/index files...
[tutorial ] ... done (0 todos, 23 index, 17 citations, 0 modules)
[tutorial ] WARNING: display latex 'V=\\QQ^3': latex exited with error
[tutorial ] [stdout]
[tutorial ] This is pdfTeX, Version 3.141592653-2.6-1.40.23 (TeX Live 2022/dev) (preloaded format=latex)
[tutorial ]  restricted \write18 enabled.
[tutorial ] entering extended mode
[tutorial ] (./math.tex
[tutorial ] LaTeX2e <2021-06-01> patch level 1
[tutorial ] L3 programming layer <2021-10-18>
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/base/article.cls
[tutorial ] Document Class: article 2021/02/12 v1.4n Standard LaTeX document class
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/base/size12.clo))
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/base/inputenc.sty)
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsmath/amsmath.sty
[tutorial ] For additional information on amsmath, use the `?' option.
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsmath/amstext.sty
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsmath/amsgen.sty))
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsmath/amsbsy.sty)
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsmath/amsopn.sty))
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amscls/amsthm.sty)
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsfonts/amssymb.sty
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsfonts/amsfonts.sty))
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/anyfontsize/anyfontsize.sty)
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/tools/bm.sty)
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/l3backend/l3backend-dvips.def)
[tutorial ] No file math.aux.
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsfonts/umsa.fd)
[tutorial ] (/usr/local/texlive/2021/texmf-dist/tex/latex/amsfonts/umsb.fd)
[tutorial ] ! Undefined control sequence.
[tutorial ] l.13 \fontsize{12}{14}\selectfont $V=\QQ
[tutorial ]                                         ^3$
[tutorial ] [1] (./math.aux) )
[tutorial ] (see the transcript file for additional information)
[tutorial ] Output written on math.dvi (1 page, 336 bytes).
[tutorial ] Transcript written on math.log.
[tutorial ] WARNING: display latex '\\QQ^3': latex exited with error
[tutorial ] [stdout]
...

and then it tries to build math.dvi half a dozen times more, failing each time.

Component: documentation

Author: Matthias Koeppe

Branch/Commit: ef2b25b

Reviewer: John Palmieri, Eric Gourgoulhon

Issue created by migration from https://trac.sagemath.org/ticket/32946

[mkoeppe]

comment:1

I think these failures are actually coming from building images for formulas.

[mkoeppe]

comment:2

Looks like I broke this in #31356 by removing the setting of SAGE_DOC_MATHJAX from src/bin/sage-env.

[mkoeppe]

comment:4

As non-mathjax builds are clearly broken, how about we just remove this whole setting?

[mkoeppe]

Branch: u/mkoeppe/_sage___docbuild_doc_html__is_broken

[mkoeppe]

Author: Matthias Koeppe

[mkoeppe]

New commits:

ef2b25b

Remove handling of broken option SAGE_DOC_MATHJAX=no

[mkoeppe]

Commit: ef2b25b

[jhpalmieri]

comment:8

Good diagnosis, this fixes the problem for me. Should there be a deprecation warning for the --mathjax/-j option for docbuilding so that we can eventually delete it?

[mkoeppe]

comment:9

I don't think there's a need to deprecate it. At some point we may want to explore using https://pypi.org/project/sphinxcontrib-katex/ instead of mathjax, and then command line options of this type will be needed again

[egourgoulhon]

comment:10

Thanks for dealing with this. Actually, I was about to post a message on sage-devel for I noticed two days ago that sage -docbuild reference/manifolds html fails with

OSError: WARNING: display latex 'K=\\RR': latex exited with error

while sage -docbuild reference/manifolds pdf succeeds, as well as make in generating the html doc.
For the moment I cannot pull the ticket branch (*), but as soon as I can do it, I'll test the fix.

(*) the command git pull trac u/mkoeppe/_sage___docbuild_doc_html__is_broken hangs. Could this be an issue with trac.sagemath.doc this morning?

[egourgoulhon]

comment:11

The trac server finally responded (after ~ 10 minutes!) and I confirm that this ticket fixes the issue with sage -docbuild ... html.

[jhpalmieri]

comment:12

Great, let's merge it!

[jhpalmieri]

Reviewer: John Palmieri, Eric Gourgoulhon

[mkoeppe]

comment:13

Thanks for reviewing!

[vbraun]

Changed branch from u/mkoeppe/_sage___docbuild_doc_html__is_broken to ef2b25b