Description
I wanted to build the PDF documentation (using Sphinx 2.2.1 and current versions of scipy, matplotlib, etc from pip install and using numpy from git at b83f10e) and was disconcerted that it actually succeeded 😉
Turns out after checking that https://github.com/numpy/numpy/blob/master/doc/source/conf.py uses removed latex_preamble variable (it was removed at Sphinx 1.6.1). Correct syntax is now with latex_elements['preamble']. I did that, and obtained the failure on building numpy-ref.pdf that I was expecting:
! Extra }, or forgotten \endgroup.
\@endpbox ...\@arstrutbox \color@endgroup \egroup
\the \LT@p@ftn \global \LT...
l.131934 \item[{Parameters}]
\leavevmode
This is caused by these lines
Lines 187 to 189 in b83f10e
I know two fixes:
- add
\usepackage{enumitem}. I don't recommend that because the fact that it fixes theexpdlistbreakage appears unintentional, it is sheer luck (and I tested it on only one small example, not the fullnumpy-ref.tex). In the past Sphinx users usedenumitemto avoidToo deeply nestederror, but since Sphinx 1.5, there islatex_elements['maxlistdepth']to fix that LaTeX limitation:
latex_elements['maxlistdepth'] = '10' # should be enough, increase at will (don't use '2048' as this would create needlessly thousands of TeX macros)
- the second fix is to be found in a scipy/scipy@c881fde and I copy it here. It would thus be like this:
% In the parameters section, place a newline after the Parameters
% header
\usepackage{expdlist}
\let\latexdescription=\description
\def\description{\latexdescription{}{} \breaklabel}
% Remove extra space
\usepackage{etoolbox}
\makeatletter
\patchcmd\@item{{\@breaklabel} }{{\@breaklabel}}{}{}
\makeatother
% Fix bug in expdlist's way of breaking the line after long item label
\makeatletter
\def\breaklabel{%
\def\@breaklabel{%
\leavevmode\par
% now a hack because Sphinx inserts \leavevmode after term node
\def\leavevmode{\def\leavevmode{\unhbox\voidb@x}}%
}%
}
\makeatotherSide remark about
Lines 182 to 183 in b83f10e
It is unneeded because already done by Sphinx
As for the remainder of the LaTeX code in this former latex_preamble it may need some check that it still gives a desired effect in the PDF.
By the way I would recommend using --halt-on-error for pdflatex builds. In case of an error, the make exits with error code but the LaTeX console output is gigantic and the log file too and one loses time searching for first TeX error, whereas with --halt-on-error this is more efficient.
The
Line 220 in b83f10e
does nothing actually with current Sphinx produced Makefile in latex build directory. You can use the method from https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder
To pass options directly to the (pdf|xe|lua)latex binary, use variable LATEXOPTS, for example:
make latexpdf LATEXOPTS="--halt-on-error"
and
Since 1.6, make latexpdf uses latexmk (not on Windows). This makes sure the needed number of runs is automatically executed to get the cross-references, bookmarks, indices, and tables of contents right.
One can pass to latexmk options via the LATEXMKOPTS Makefile variable. For example:
make latexpdf LATEXMKOPTS="-silent"
(this is with standard Sphinx distributed Makefile, in your case replace latexpdf by -C build/latex all-pdf) and the two can be combined but then (with patches of expdlist above commented out) the LaTeX error does not make it to the console output only to the end of the log file:
$ make numpy-ref.pdf LATEXOPTS="--halt-on-error" LATEXMKOPTS="--silent"
latexmk -pdf -dvi- -ps- --silent 'numpy-ref.tex'
Latexmk: Run number 1 of rule 'makeindex numpy-ref.idx'
Latexmk: Run number 1 of rule 'pdflatex'
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019) (preloaded format=pdflatex)
restricted \write18 enabled.
entering extended mode
Latexmk: Summary of warnings from last run of (pdf)latex:
Latex found 4 multiply defined reference(s)
Latex failed to resolve 388 citation(s)
Collected error summary (may duplicate other messages):
pdflatex: Command for 'pdflatex' gave return code 1
Refer to 'numpy-ref.log' for details
Latexmk: Use the -f option to force complete processing,
unless error was exceeding maximum runs, or warnings treated as errors.
make: *** [Makefile:33: numpy-ref.pdf] Error 12
One has to go in numpy-ref.log find the LaTeX error causing abort:
! Extra }, or forgotten \endgroup.
\@endpbox ...\@arstrutbox \color@endgroup \egroup
\the \LT@p@ftn \global \LT...
l.131952 \item[{Parameters}]
\leavevmode
Here is how much of TeX's memory you used:
26928 strings out of 493377
686470 string characters out of 6157389
755139 words of memory out of 5000000
26189 multiletter control sequences out of 15000+600000
84239 words of font info for 133 fonts, out of 8000000 for 9000
500 hyphenation exceptions out of 8191
51i,26n,49p,1225b,732s stack positions out of 5000i,500n,10000p,200000b,80000s
! ==> Fatal error occurred, no output PDF file produced!
To recap, numpy-ref.pdf builds currently because latex_preamble from doc/source/conf.py is ignored! If this LaTeX configuration was not ignored, the build would fail due to usage of very old (1999) LaTeX package expdlist which causes usage of description lists in table cells break LaTeX (and there is one such usage subsection distutils.misc from section Modules in numpy.distuils part of numpy-ref). A fix is known from an April 2018 scipy commit scipy/scipy@c881fde.