matplotlib
diff --git a/‎doc/conf.py
Lines changed: 74 additions & 27 deletions b/‎doc/conf.py
Lines changed: 74 additions & 27 deletions
@@ -308,29 +308,83 @@ def _check_dependencies():
 latex_logo = None
 
 latex_elements = {}
+
+latex_engine = 'xelatex'  # many Unicode glyphs in our docs...
+# By default Sphinx with latex_engine = 'xelatex' uses polyglossia
+# If this key is changed, clean the build/latex directory before next build
+latex_elements['babel'] = r'\usepackage{babel}'
+
 # Additional stuff for the LaTeX preamble.
-latex_elements['preamble'] = r"""
-   % In the parameters section, place a newline after the Parameters
-   % header.  (This is stolen directly from Numpy's conf.py, since it
-   % affects Numpy-style docstrings).
-   \usepackage{expdlist}
-   \let\latexdescription=\description
-   \def\description{\latexdescription{}{} \breaklabel}
-
-   \usepackage{amsmath}
-   \usepackage{amsfonts}
-   \usepackage{amssymb}
-   \usepackage{txfonts}
-
-   % The enumitem package provides unlimited nesting of lists and
-   % enums.  Sphinx may use this in the future, in which case this can
-   % be removed.  See
-   % https://bitbucket.org/birkenfeld/sphinx/issue/777/latex-output-too-deeply-nested
-   \usepackage{enumitem}
-   \setlistdepth{2048}
-"""
+
+# Usage of expdlist package (as originally copied over from Numpy's confpy)
+# is removed because it breaks the PDF build with recent LaTeX:
+#    ! Extra }, or forgotten \endgroup.
+#      \@endpbox ...\@arstrutbox \color@endgroup \egroup
+# The https://github.com/scipy/scipy/pull/8657 code would actually fix this
+#
+# latex_elements['preamble'] = r"""
+#    % In the parameters section, place a newline after the Parameters
+#    % header.  (This is stolen directly from Numpy's conf.py, since it
+#    % affects Numpy-style docstrings).
+#    \usepackage{expdlist}
+#    \let\latexdescription=\description
+#    \def\description{\latexdescription{}{} \breaklabel}
+# """
+
 latex_elements['pointsize'] = '11pt'
 
+# Fix fancyhdr complaining about \headheight too small
+latex_elements['passoptionstopackages'] = r"""
+    \PassOptionsToPackage{headheight=14pt}{geometry}
+"""
+
+# Sphinx 1.5 provides this to avoid "too deeply nested" LaTeX error
+# and usage of "enumitem" LaTeX package is unneeded.
+# Value can be increased but do not set it to something such as 2048
+# which needlessly would trigger creation of thousands of TeX macros
+latex_elements['maxlistdepth'] = '10'
+
+# Use OpenType font with wide-enough glyph coverage
+# Sphinx 2.0 adopts GNU FreeFont by default, but it does not have all
+# the Unicode codepoints needed for the section about Mathtext
+# "Writing mathematical expressions"
+latex_elements['fontpkg'] = r"""
+\setmainfont{XITS}[
+  Extension      = .otf,
+  UprightFont    = *-Regular,
+  ItalicFont     = *-Italic,
+  BoldFont       = *-Bold,
+  BoldItalicFont = *-BoldItalic,
+]
+\setsansfont{FreeSans}[
+  Extension      = .otf,
+  UprightFont    = *,
+  ItalicFont     = *Oblique,
+  BoldFont       = *Bold,
+  BoldItalicFont = *BoldOblique,
+]
+\setmonofont{FreeMono}[
+  Extension      = .otf,
+  UprightFont    = *,
+  ItalicFont     = *Oblique,
+  BoldFont       = *Bold,
+  BoldItalicFont = *BoldOblique,
+]
+% \usepackage{unicode-math}
+% \setmathfont{XITS Math}
+"""
+# Last two lines commented out because only there to fix missing glyphs from
+# one \mathbb{blackboard}, and anyhow the whole section about Mathtext Fonts
+# is broken as it would need extra LaTeX raw directives to actually switch
+# math fonts from main one and illustrate the "five global font sets". For
+# this one must define math versions in the LaTeX preamble and it is all quite
+# cumbersome.
+
+# Sphinx <1.8.0 or >=2.0.0 does this by default, but the 1.8.x series
+# did not for latex_engine = 'xelatex' (used Latin Modern font).
+# We need it as FreeMono has wide character glyphs.
+latex_elements['fvset'] = r'\fvset{fontsize=\small}'
+
 # Documents to append as an appendix to all manuals.
 latex_appendices = []
 
@@ -358,13 +412,6 @@ def _check_dependencies():
 
 numpydoc_show_class_members = False
 
-latex_engine = 'xelatex'  # or 'lualatex'
-
-latex_elements = {
-    'babel': r'\usepackage{babel}',
-    'fontpkg': r'\setmainfont{DejaVu Serif}',
-}
-
 html4_writer = True
 
 inheritance_node_attrs = dict(fontsize=16)