Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] PDF build of matplotlib own documentation crashes with LaTeX error "too deeply nested" #15796

Closed
jfbu opened this issue Nov 30, 2019 · 0 comments
Milestone

Comments

@jfbu
Copy link
Contributor

jfbu commented Nov 30, 2019

This is with Sphinx 2.2.1 and Python 3.7.5. make latexpdf SPHINXOPTS= aborts with

! LaTeX Error: Too deeply nested.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.152900 \begin{itemize}

Recap of sphinx-doc/sphinx#6871 (comment):

I will submit a PR to fix this and some font issues: 134 distinct characters are missing from the DejaVu Serif font used by the current conf.py, only 19 if using GNU FreeFont which is Sphinx default since 2.0.0, from documentation of Mathtext which has lots of Unicode math symbols in plain text. Using XITS font, (possibly STIX2 works too but not tested) all characters are there (apart from one usage of \mathbb{blackboard} where b, c, d are actually missing from default blackboard font -- this can be fixed using XITS Math but requires \usepackage{unicode-math} which is heavy LaTeX package only to fix this issue in a section which anyhow is broken in PDF because it documents distinct fonts, and PDF is using only one -- it is complicated to use multiple fonts as this would require raw directives -- also, generally speaking LaTeX has no convenient fall-back choice of fonts for individual characters, one can achieve this only by some extra mark-up or LaTeX code, thus it is important to have as wide coverage as possible for the chosen main document font.

This is with a pip editable install of matplotlib master at 3d1a1bcc

jfbu added a commit to jfbu/matplotlib that referenced this issue Nov 30, 2019
Already sphinx>=1.8.1 is a requirement, and 'maxlistdepth' is available
since Sphinx 1.5.

This commit also suppresses usage of LaTeX expdlist package as it breaks
PDF builds with recent LaTeX (2019 at least). The April 2018 code at
scipy/scipy#8657 which patched expdlist for
other reasons appears to fix also this issue and could be added here.

Also, this commit sets up XITS as main document font: usage of XITS
achieves that the section documenting Mathtext does not report missing
glyphs during the LaTeX build. Probably STIX2 would work too. (with
DejaVu Serif, there were 134 unique Unicode glyphs needed by the PDF
build and reported missing from the font).

XITS font is available in LaTeX distributions of recent years.

This commit was tested with Sphinx v1.8.5 and Sphinx v2.2.1.
(and using current TeXLive TeX distribution)
@jfbu jfbu changed the title [DOC] PDF build of own documentation crashes with LaTeX error "too deeply nested" [DOC] PDF build of matplotlib own documentation crashes with LaTeX error "too deeply nested" Nov 30, 2019
jfbu added a commit to jfbu/matplotlib that referenced this issue Dec 2, 2019
Already sphinx>=1.8.1 is a requirement, and 'maxlistdepth' is available
since Sphinx 1.5.

This commit also suppresses usage of LaTeX expdlist package as it breaks
PDF builds when a description list is in a table cell. Which actually
happens with matplotlib doc on master branch at 3d1a1bc (end 11/2019).

A scipy commit
scipy/scipy@c881fde
of April 2018 has a patch of expdlist command \breaklabel which would fix
that LaTeX issue, but here we simply comment out usage of expdlist.

Last but not least, this commit sets up XITS as main document font:
usage of XITS achieves that the section documenting Mathtext does not
report missing glyphs during the LaTeX build. Probably STIX2 would work
too. With DejaVu Serif, there were 134 unique Unicode glyphs needed by
the PDF build and missing from the font hence from the produced PDF.

XITS font is available in LaTeX distributions of recent years.

This commit was tested with Sphinx v1.8.5 and Sphinx v2.2.1.
(and using current TeXLive TeX distribution)
jfbu added a commit to jfbu/matplotlib that referenced this issue Dec 5, 2019
This commit reactivates original latex_elements['preamble'] key which
was shadowed by the bug about latex_elements being defined twice in the
conf.py.

It removes from this latex preamble the loading of amsmath, amssymb,
amsfonts as this is already added by Sphinx, and of txfonts because this
is not compatible with fontspec and the already executed command
\setmainfont{DejaVu Serif}.

Memo: expdlist package breaks PDF build if a description list ends up in
a table cell, as happens actually with Matplotlib.tex file. But, by
luck, the enumitem LaTeX package modifications of LaTeX description
lists masks the expdlist potential breakage.
jfbu added a commit to jfbu/matplotlib that referenced this issue Mar 22, 2020
- remove loading of amsmath, amssymb, amsfonts (already done by
  sphinx.sty)
- remove loading of txfonts (not compatible with xetex/fontspec)
- patch old obsolete expdlist.sty
- resolve "Too deeply nested" error without using enumitem package.
  This Imports the fix already applied to NumPy and SciPy

    numpy/numpy#15028
    scipy/scipy@c881fde

- use XITS and XITS Math for wide enough Unicode coverage. As XITS has
  all the Unicode mathematical symbols needed for the section of the
  documentation related to Mathtext.
  (DejaVu Serif was missing 134 of them, and GNU FreeFont 19 of them)

  The Ubuntu package texlive-fonts-extra provides these latex dependencies.

- better looking general index in PDF documentation
- backport sphinx-doc/sphinx/pull/6888 to fix double quote issue
@QuLogic QuLogic added this to the v3.4.0 milestone Dec 17, 2020
QuLogic pushed a commit to QuLogic/matplotlib that referenced this issue Dec 17, 2020
This commit reactivates original latex_elements['preamble'] key which
was shadowed by the bug about latex_elements being defined twice in the
conf.py.

It removes from this latex preamble the loading of amsmath, amssymb,
amsfonts as this is already added by Sphinx, and of txfonts because this
is not compatible with fontspec and the already executed command
\setmainfont{DejaVu Serif}.

Memo: expdlist package breaks PDF build if a description list ends up in
a table cell, as happens actually with Matplotlib.tex file. But, by
luck, the enumitem LaTeX package modifications of LaTeX description
lists masks the expdlist potential breakage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants