[DOC] doc/source/conf.py contains usage of latex_preamble which was removed at Sphinx 1.6.1 #15026

jfbu · 2019-12-02T13:56:11Z

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

numpy/doc/source/conf.py

Lines 187 to 189 in b83f10e

    
           \usepackage{expdlist} 
        
           \let\latexdescription=\description 
        
           \def\description{\latexdescription{}{} \breaklabel}

I know two fixes:

add \usepackage{enumitem}. I don't recommend that because the fact that it fixes the expdlist breakage appears unintentional, it is sheer luck (and I tested it on only one small example, not the full numpy-ref.tex). In the past Sphinx users used enumitem to avoid Too deeply nested error, but since Sphinx 1.5, there is latex_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}}%
    }%
}
\makeatother

Side remark about

numpy/doc/source/conf.py

Lines 182 to 183 in b83f10e

    
           \usepackage{amsmath} 
        
           \DeclareUnicodeCharacter{00A0}{\nobreakspace}

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

numpy/doc/Makefile

Line 220 in b83f10e

    
           perl -pi -e 's/\t(latex.*|pdflatex) (.*)/\t-$$1 -interaction batchmode $$2/' build/latex/Makefile

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.

The text was updated successfully, but these errors were encountered:

jfbu · 2019-12-02T14:36:02Z

By the way the "Parameters" in a table comes from an automsummary directive in file https://github.com/numpy/numpy/blob/master/doc/source/reference/distutils.rst

.. autosummary::
   :toctree: generated/

   ccompiler
   cpuinfo.cpu
   core.Extension
   exec_command
   log.set_verbosity
   system_info.get_info
   system_info.get_standard_file

and in particular the core.Extension. I did not investigate further. PDF looks like this:

and the tex source has

\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\end{description}\end{quote}

inside a longtable cell. There might be something wrong with my testing obviously because I skipped building numpy itself!!!

WarrenWeckesser · 2019-12-02T14:57:10Z

Thanks @jfbu. Would you be interested in creating a pull request with these changes?

jfbu · 2019-12-02T19:50:21Z

@WarrenWeckesser thanks for proposal, done at #15028

eric-wieser added 00 - Bug component: documentation labels Dec 2, 2019

mattip closed this as completed in 4bc7eda Dec 4, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] doc/source/conf.py contains usage of latex_preamble which was removed at Sphinx 1.6.1 #15026

[DOC] doc/source/conf.py contains usage of latex_preamble which was removed at Sphinx 1.6.1 #15026

jfbu commented Dec 2, 2019

jfbu commented Dec 2, 2019

WarrenWeckesser commented Dec 2, 2019

jfbu commented Dec 2, 2019

[DOC] doc/source/conf.py contains usage of latex_preamble which was removed at Sphinx 1.6.1 #15026

[DOC] doc/source/conf.py contains usage of latex_preamble which was removed at Sphinx 1.6.1 #15026

Comments

jfbu commented Dec 2, 2019

jfbu commented Dec 2, 2019

WarrenWeckesser commented Dec 2, 2019

jfbu commented Dec 2, 2019