Closes #15796 (building PDF docs of matplotlib via LaTeX) #15797
Conversation
|
Forced pushed to reword a commit message. I had forgotten that in scipy/scipy@c881fde (from scipy/scipy#8657) I had already found out that edit: turns out that the breakage caused by old buggy I try hard to be very focused and to not dwell on long LaTeX inherent complications and explanations about bad or badly interacting packages but I always end up piling up paragraphs... |
|
on further thought and having experimented with building numpy's docs to PDF, and now remembering better my similar experience with building scipy's PDF docs, I think it would be better for coherence with these two other projects (who probably have many shared users with matplotlib project) to not comment out usage of (highlighting of Parameters in above screenshot is accidental, my PDF viewer was used to search for that string) |
|
I have pushed some more commits. Sorry about mishap with
Before: After:
Before: After: LaTeX installation must have And https://github.com/alif-type/xits fonts are needed. Ubuntu's texlive-fonts-extra provided it at xenial already. And nota bene: while working on this I have noticed a problem with See sphinx-doc/sphinx#6886. It is possible the issue does not show with old LaTeX, because fontspec package according to its docs in some (unspecified) past state did not activate so-called TeX ligatures by default. But now (since when?) it does it by default. By the way I do not understand why the mapping |
Ah sorry when I updated this one I had forgotten about #15799... and I incorporated here in my last update half of it, i.e. usage of Better to keep the two separated, but when I will update #15799 to only contain the fix of author display on title page, part of your reviewing work over there will be marked "outdated"... because it was on commits which will be only in this one soon. (my rationale into incorporating into #15799 the commits present here was to allow testing the PDF build, but if you trust the picture I posted over there it is not really needed....)
Ok, I will clean up a bit this branch. And add a commit backporting the method sphinx-doc/sphinx/pull/6888 fix of the double quote issue when using
|
|
I have force pushed to reorganize the commit history and messages into logically consecutive steps. |
|
e01fe33 seems to have the wrong commit message (and could be merged with the following commit.) Otherwise, I think this looks reasonable, though I have yet to test it. |
|
I tried this out, but even after installing the The file name is |
|
Ah, I see we have this in our pgf documentation; xelatex can't find fonts installed in texlive directories instead of globally. I worked around this by giving it the file name However, it also failed to find |
The situation is a wee'bit complicated with xelatex+fontspec for fonts, things have changed overtime. On my mac os x, I have a special set-up with symlinks in $HOME/Library/Fonts to point to the TrueType and OpenType repertories in the TeXLive tree. However I often forget I had long time ago set-up these symlinks and this may lead me to have a smoother ride than some users (on mac os). As per Linux I can test on Ubuntu but I have no Fedora handy. On TeXLIve based distribution, if xelatex does not find the font in system/user locations it will then, it can still find it indeed by filename via the services of kpsewhich which comes with these distributions.
should I add another setting (using filename for XITS Math) and then squash commits? |
|
It should definitely work with a default setup, not sure if an option would be needed. |
- 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
modified: doc/conf.py
|
Squashed and rebased to get a clear commit message. I don't know what to do for XITS loading. Here is my local set-up: On my mac os x, filenames ignore case. So I could use |
|
The file names for XITS on Fedora are like |
|
Any progress here? What needs to be done? |
|
I installed a clean mactex (mactex-20200407.pkg) from homebrew on Catalina and upgraded all packages with I think xetex shouldn't need TeX font metrics, so it shouldn't be calling mktextfm. |
|
Editing the file like so allows the build to continue: \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{XITSMath-Regular}[
Extension = .otf
]Would this work on Linux? |
|
Here's a Dockerfile for testing on Fedora: FROM fedora:latest
RUN dnf install -y texlive-xetex texlive-xits latexmk \
'tex(cmap.sty)' \
'tex(FreeSans.otf)' \
'tex(fncychap.sty)' \
'tex(fancyhdr.sty)' \
'tex(titlesec.sty)' \
'tex(tabulary.sty)' \
'tex(longtable.sty)'\
'tex(varwidth.sty)' \
'tex(makeidx.sty)' \
'tex(framed.sty)' \
'tex(xcolor.sty)' \
'tex(fancyvrb.sty)' \
'tex(float.sty)' \
'tex(wrapfig.sty)' \
'tex(parskip.sty)' \
'tex(alltt.sty)' \
'tex(upquote.sty)' \
'tex(capt-of.sty)' \
'tex(needspace.sty)'\
'tex(remreset.sty)' \
'tex(atbegshi.sty)' \
'tex(kvoptions.sty)'\
'tex(expdlist.sty)'
COPY . $HOME
RUN latexmk -pdf -dvi- -ps- Matplotlib.texCalling |
There was a problem hiding this comment.
Suggestion based on https://tex.stackexchange.com/a/325964/3510
| # the Unicode codepoints needed for the section about Mathtext | ||
| # "Writing mathematical expressions" | ||
| latex_elements['fontpkg'] = r""" | ||
| \setmainfont{XITS}[ |
There was a problem hiding this comment.
| \setmainfont{XITS}[ | |
| \setmainfont{XITS}[ | |
| Extension = .otf, |
| BoldFont = *-Bold, | ||
| BoldItalicFont = *-BoldItalic, | ||
| ] | ||
| \setsansfont{FreeSans}[ |
There was a problem hiding this comment.
| \setsansfont{FreeSans}[ | |
| \setsansfont{FreeSans}[ | |
| Extension = .otf, |
| BoldFont = *Bold, | ||
| BoldItalicFont = *BoldOblique, | ||
| ] | ||
| \setmonofont{FreeMono}[ |
There was a problem hiding this comment.
| \setmonofont{FreeMono}[ | |
| \setmonofont{FreeMono}[ | |
| Extension = .otf, |
| ] | ||
| % needed for \mathbb (blackboard alphabet) to actually work | ||
| \usepackage{unicode-math} | ||
| \setmathfont{XITS Math} |
There was a problem hiding this comment.
| \setmathfont{XITS Math} | |
| \setmathfont{XITSMath-Regular}[ | |
| Extension = .otf | |
| ] |
You need to install |
|
That won't work for Fedora, because it has |
|
I rebased this and added additional fixes for new bugs in the above-linked PR. |
PR Summary
Make build of matplotlib documentation to PDF possible.
The #15796 issue is caused by the fact that
latex_elementsdict got redefined near end ofconf.pyhence the part about using LaTeX package enumitem and its\setlistdepthgot lost. But anyway since Sphinx 1.5 there is'maxlistdepth'key, so use that.Another problem arose related to
expdlistvery old LaTeX package. I realized it broke the buildwith recent LaTeX(when a description environment was found in a longtable cell).edited: this also breaks with LaTeX as old as 2012. Because I did not recall having seen the issue in 2018 when trying out building scipy's PDF documentation (but perhaps I had already patched
expdlist), and as my laptop only has TeXLive 2018 and 2019 I erroneously thought the issue arose from LaTeX upstream change of array package. But I see nowexpdlist(not updated since 1999...) breaks LaTeX (even from 2012) when a description list ends up in a table cell. It is not recent issue.The cause is probably the upstream LaTeX changes in array package which last year invalidated tabu package.For time being I simply commented out usage of
expdlist. Turns out that a patch of mine which got merged into scipy (also for matters of building PDF) in April 2018 fixes themore recentbreakage caused byexpdlist. As experimenting with builds of matplotlib (close to 3000 pages) is time costly, I did not much investigate if it would be worthwile usingexpdlistas patched in my scipy PR. (see commit message).Finally, matplotlib documentation of "Mathtext" uses tons of Unicode math-like characters in plain text, and DejaVu Serif was lacking 134 of them. I thus configure the build to use XITS and it turns out it provided all glyphs. It comes with TeXLive TeX distributions of recent years. I used syntax which should work whether compiling on Mac OS or Linux and probably Windows.
As latex engine is xelatex, it is not easy without additional mark-up to use both OpenType fonts and traditional TeX fonts, so I removed the
\usepackage{txfonts}and used FreeSans and FreeMono for the sans and mono famillies. This means though that the math symbols will be the Knuth Computer Modern ones. I left commented out two lines loadingunicode-mathand the OpenType Math fontXITS Mathwhich would fix that aspect. Perhaps they should be activated ?PR Checklist
almost None of this applies because it is simply a modification of
doc/conf.py...Arrgh
but... none of this comes from my patch as it is all after line number 300 :-)
Tested the PDF build with Sphinx 1.8.5 and 2.2.1 and Python 3.7.5 and matplotlib at 3d1a1bc