From 8b6e341d34267149a85588b4181652318c8a7178 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 5 Dec 2019 10:00:27 +0100 Subject: [PATCH 01/10] Closes #15796: latex_elements defined twice in doc/conf.py 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. --- doc/conf.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 210d8f2b03f4..cd848cf28079 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -342,7 +342,19 @@ def _check_dependencies(): # the title page. latex_logo = None +# Use Unicode aware LaTeX engine +latex_engine = 'xelatex' # or 'lualatex' + latex_elements = {} + +# Keep babel usage also with xelatex (Sphinx default is polyglossia) +# If this key is removed or changed, latex build directory must be cleaned +latex_elements['babel'] = r'\usepackage{babel}' + +# Font configuration +# Sphinx default since 2.x is GNU FreeFont +latex_elements['fontpkg'] = r'\setmainfont{DejaVu Serif}' + # Additional stuff for the LaTeX preamble. latex_elements['preamble'] = r""" % One line per author on title page @@ -355,11 +367,6 @@ def _check_dependencies(): \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 @@ -393,13 +400,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) From 2b212a0e7222274b0b825e11b04612d19850b11b Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 5 Dec 2019 10:19:06 +0100 Subject: [PATCH 02/10] LaTeX: resolve "Too deeply nested" error without enumitem package But removing enumitem package reveals a bug in expdlist. Import the fix from the SciPy and NumPy projects. https://github.com/numpy/numpy/pull/15028 https://github.com/scipy/scipy/commit/c881fdea7a7ef7c518b7898cfd53b2880af06778 --- doc/conf.py | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index cd848cf28079..e8375327a7a0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -360,20 +360,31 @@ def _check_dependencies(): % One line per author on title page \DeclareRobustCommand{\and}% {\end{tabular}\kern-\tabcolsep\\\begin{tabular}[t]{c}}% - % 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} - - % 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} + % But expdlist old LaTeX package requires fixes: + % 1) remove extra space + \usepackage{etoolbox} + \makeatletter + \patchcmd\@item{{\@breaklabel} }{{\@breaklabel}}{}{} + \makeatother + % 2) 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 """ +# 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' latex_elements['pointsize'] = '11pt' # Documents to append as an appendix to all manuals. From 53d417051538885422e96316a49251ff1850c2fb Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 5 Dec 2019 10:31:31 +0100 Subject: [PATCH 03/10] LaTeX: use XITS and XITS Math for wide enough Unicode coverage XITS has all the Unicode mathematical symbols glyphs needed for the section of the documentation related to Mathtext. (DejaVu Serif was missing 134 of them, and GNU FreeFont 19 of them) XITS Math (and unicode-math) is needed for \mathbb supporting letters b, c, d, there is one \mathbb{blackboard} once in the documentation. It also gives better calligraphy font. The Ubuntu package texlive-fonts-extra provides these latex dependencies. --- doc/conf.py | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index e8375327a7a0..b22cb1877e54 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -352,8 +352,43 @@ def _check_dependencies(): latex_elements['babel'] = r'\usepackage{babel}' # Font configuration -# Sphinx default since 2.x is GNU FreeFont -latex_elements['fontpkg'] = r'\setmainfont{DejaVu Serif}' +# 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, +] +% needed for \mathbb (blackboard alphabet) to actually work +\usepackage{unicode-math} +\setmathfont{XITS Math} +""" +# Sphinx <1.8.0 or >=2.0.0 does this by default, but the 1.8.x series +# did not for latex_engine = 'xelatex' (as it used Latin Modern font). +# We need this for code-blocks as FreeMono has wide glyphs. +latex_elements['fvset'] = r'\fvset{fontsize=\small}' +# Fix fancyhdr complaining about \headheight being too small +latex_elements['passoptionstopackages'] = r""" + \PassOptionsToPackage{headheight=14pt}{geometry} +""" # Additional stuff for the LaTeX preamble. latex_elements['preamble'] = r""" From 8d9ebb5561619ddb6aac1103737ba49bf665a66d Mon Sep 17 00:00:00 2001 From: jfbu Date: Sat, 30 Nov 2019 19:20:24 +0100 Subject: [PATCH 04/10] Better looking general index in PDF documentation modified: doc/conf.py --- doc/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index b22cb1877e54..a07e6a80de20 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -422,6 +422,9 @@ def _check_dependencies(): latex_elements['maxlistdepth'] = '10' latex_elements['pointsize'] = '11pt' +# Better looking general index in PDF +latex_elements['printindex'] = r'\footnotesize\raggedright\printindex' + # Documents to append as an appendix to all manuals. latex_appendices = [] From e6b341d3a26cac91eb7d6dc476a6df60ca0ad27d Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 5 Dec 2019 11:02:01 +0100 Subject: [PATCH 05/10] LaTeX: backport sphinx-doc/sphinx/pull/6888 to fix double quote issue --- doc/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index a07e6a80de20..b942ad98fa89 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -352,6 +352,12 @@ def _check_dependencies(): latex_elements['babel'] = r'\usepackage{babel}' # Font configuration +# Fix fontspec converting " into right curly quotes in PDF +# cf https://github.com/sphinx-doc/sphinx/pull/6888/ +latex_elements['fontenc'] = r''' +\usepackage{fontspec} +\defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{} +''' # 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" From 3947e83613549878240d1d0e2a1d01734a87a47d Mon Sep 17 00:00:00 2001 From: jfbu Date: Sun, 22 Mar 2020 09:12:38 +0100 Subject: [PATCH 06/10] Drop Extension = .otf lines from LaTeX font loading modified: doc/conf.py --- doc/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index b942ad98fa89..78ef13b98f17 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -363,21 +363,18 @@ def _check_dependencies(): # "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, From 89b6314e55e47a6a2b7fc1a13c34040dc9a52c71 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Fri, 13 Nov 2020 00:35:56 -0500 Subject: [PATCH 07/10] Add missing dimension in genfrac LaTeX example. This appears unnecessary in mathtext, but LaTeX requires the dimension. --- tutorials/text/mathtext.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/text/mathtext.py b/tutorials/text/mathtext.py index 8c67142e1dc5..3663d27f5f8b 100644 --- a/tutorials/text/mathtext.py +++ b/tutorials/text/mathtext.py @@ -94,7 +94,7 @@ .. math:: - \frac{3}{4} \binom{3}{4} \genfrac{}{}{0}{}{3}{4} + \frac{3}{4} \binom{3}{4} \genfrac{}{}{0pt}{}{3}{4} Fractions can be arbitrarily nested:: From cd30a70d93d97ee2c92d38abde0e1643101fefd9 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Fri, 13 Nov 2020 00:36:56 -0500 Subject: [PATCH 08/10] DOC: Fix some bugs in math symbol tables. Limit math symbol table columns to number of symbols. In Hebrew, there are only 4 symbols, but the table is 6 columns with two extra empty columns. Fix Delimiters table as pipe and backslash need to be escaped. Replace the `get_n` function with a simpler `range` operation. --- doc/sphinxext/math_symbol_table.py | 36 +++++++++++------------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/doc/sphinxext/math_symbol_table.py b/doc/sphinxext/math_symbol_table.py index f12b9887e349..3041b15b36a8 100644 --- a/doc/sphinxext/math_symbol_table.py +++ b/doc/sphinxext/math_symbol_table.py @@ -100,38 +100,28 @@ def run(state_machine): - def get_n(n, l): - part = [] - for x in l: - part.append(x) - if len(part) == n: - yield part - part = [] - yield part + def render_symbol(sym): + if sym.startswith("\\"): + sym = sym[1:] + if sym not in {*mathtext.Parser._overunder_functions, + *mathtext.Parser._function_names}: + sym = chr(mathtext.tex2uni[sym]) + return f'\\{sym}' if sym in ('\\', '|') else sym lines = [] for category, columns, syms in symbols: syms = sorted(syms.split()) + columns = min(columns, len(syms)) lines.append("**%s**" % category) lines.append('') max_width = max(map(len, syms)) * 2 + 16 header = " " + (('=' * max_width) + ' ') * columns lines.append(header) - for part in get_n(columns, syms): - line = ( - " " + - " ".join( - "{} ``{}``".format( - sym - if not sym.startswith("\\") - else sym[1:] - if (sym[1:] in mathtext.Parser._overunder_functions - or sym[1:] in mathtext.Parser._function_names) - else chr(mathtext.tex2uni[sym[1:]]), - sym) - .rjust(max_width) - for sym in part)) - lines.append(line) + for part in range(0, len(syms), columns): + row = " ".join( + f"{render_symbol(sym)} ``{sym}``".rjust(max_width) + for sym in syms[part:part + columns]) + lines.append(f" {row}") lines.append(header) lines.append('') From 2bec173bfb6381b168bb5142bb4ef34ea7421c6d Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Fri, 13 Nov 2020 02:45:52 -0500 Subject: [PATCH 09/10] DOC: Put bibliography/indices in their own Part. When the Glossary existed, they would go in there, but now they are stuck at the end of the Developer Guide. Neither was really correct, so now they are in their own Part. --- doc/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 78ef13b98f17..210382c1bbb1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -398,12 +398,13 @@ def _check_dependencies(): % One line per author on title page \DeclareRobustCommand{\and}% {\end{tabular}\kern-\tabcolsep\\\begin{tabular}[t]{c}}% + \usepackage{etoolbox} + \AtBeginEnvironment{sphinxthebibliography}{\appendix\part{Appendices}} \usepackage{expdlist} \let\latexdescription=\description \def\description{\latexdescription{}{} \breaklabel} % But expdlist old LaTeX package requires fixes: % 1) remove extra space - \usepackage{etoolbox} \makeatletter \patchcmd\@item{{\@breaklabel} }{{\@breaklabel}}{}{} \makeatother From 2fd6983a9541a28ac9b1e333754ec4e364339a59 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Tue, 8 Dec 2020 05:20:45 -0500 Subject: [PATCH 10/10] DOC: Add explicit font filenames for some TeX systems. On macOS, xelatex uses the system font directories, but MacTeX fonts are not added there. However, these files can be found by specifying the file name instead of the font name, so do so on macOS. On Linux, it is mostly better to continue to specify the font name, as different distros ship different extensions. This should still work on systems that don't do this, using the same fallback as macOS. --- doc/conf.py | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 210382c1bbb1..039f91cf1ecc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -358,32 +358,52 @@ def _check_dependencies(): \usepackage{fontspec} \defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{} ''' + # 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}[ +fontpkg = r""" +\IfFontExistsTF{XITS}{ + \setmainfont{XITS} +}{ + \setmainfont{XITS}[ + Extension = .otf, UprightFont = *-Regular, ItalicFont = *-Italic, BoldFont = *-Bold, BoldItalicFont = *-BoldItalic, -] -\setsansfont{FreeSans}[ +]} +\IfFontExistsTF{FreeSans}{ + \setsansfont{FreeSans} +}{ + \setsansfont{FreeSans}[ + Extension = .otf, UprightFont = *, ItalicFont = *Oblique, BoldFont = *Bold, BoldItalicFont = *BoldOblique, -] -\setmonofont{FreeMono}[ +]} +\IfFontExistsTF{FreeMono}{ + \setmonofont{FreeMono} +}{ + \setmonofont{FreeMono}[ + Extension = .otf, UprightFont = *, ItalicFont = *Oblique, BoldFont = *Bold, BoldItalicFont = *BoldOblique, -] +]} % needed for \mathbb (blackboard alphabet) to actually work \usepackage{unicode-math} -\setmathfont{XITS Math} +\IfFontExistsTF{XITS Math}{ + \setmathfont{XITS Math} +}{ + \setmathfont{XITSMath-Regular}[ + Extension = .otf, +]} """ +latex_elements['fontpkg'] = fontpkg + # Sphinx <1.8.0 or >=2.0.0 does this by default, but the 1.8.x series # did not for latex_engine = 'xelatex' (as it used Latin Modern font). # We need this for code-blocks as FreeMono has wide glyphs.