Fix Sphinx conf.py to successfully build doc as PDF
#31735
Conversation
`luatex` is a Unicode TeX engine that can load OTF or TTF font that are more completed than T1 encoding fonts used by `pdflatex`. Loading `unidoce-math` also math mode use a TTF font, Latin Modern (a modern variant of Computer Modern by Knuth). At the time of writing two different fonts are used: [GNU FreeFont](https://www.gnu.org/software/freefont/index.html) for text mode and [`latinmodern-math`](https://www.gust.org.pl/projects/e-foundry/lm-math) for math mode.
|
We've decided to stop generating pdf docs: #17051 |
|
@miticollo we would welcome a documentation contribution to give people guidance on how to generate a pdf themselves - ref: #20859 |
|
@lucyleeow As reported here a user can generate a PDF using |
|
From the Make file it looks like we used the pdflatex engine previously. If we want to change the engine, we should probably have a discussion first. |
| @@ -537,7 +538,7 @@ def add_js_css_files(app, pagename, templatename, context, doctree): | |||
| # [howto/manual]). | |||
| latex_documents = [ | |||
| ( | |||
| "contents", | |||
| root_doc, | |||
There was a problem hiding this comment.
This seems clearer
| root_doc, | |
| "index", |
There was a problem hiding this comment.
This change should be sufficient to produce doc/_build/latex/user_guide.tex. Unfortunately, running make _build/latex all-pdf into doc/ using PDFLaTeX there are some issues. Six of them can be manually solved. But pdftex is not a Unicode engine, so it can't load TTF or OTF fonts. It uses T1 or OT1 (7 bit) encoding fonts, for this reason PDF compilation fails. This can be solved using an engine that support Unicode fonts, like xetex that supports them naively or luatex that supports them using luaotfload. To be more precise, even with LuaLaTeX a manual action is required to fix these six issues and correctly build PDF.
There was a problem hiding this comment.
Thanks for the context, it seems reasonable to change tex engine, though we should probably update mentions of pdftex.
This seems like the minimal changes to allow the pdf to at least build.
manual action is required to fix these six issues and correctly build PDF.
yes I think this is why we decided to stop building pdf.
| latex_elements = { | ||
| # The paper size ('letterpaper' or 'a4paper'). | ||
| # 'papersize': 'letterpaper', | ||
| # The font size ('10pt', '11pt' or '12pt'). | ||
| # 'pointsize': '10pt', | ||
| # Additional stuff for the LaTeX preamble. | ||
| "preamble": r""" | ||
| \usepackage{amsmath}\usepackage{amsfonts}\usepackage{bm} | ||
| \usepackage{unicode-math} |
There was a problem hiding this comment.
Can you explain this change? Are the old packages no longer supported or?
There was a problem hiding this comment.
amsmath is already loaded by Sphinx, anyway unicode-math loads this package if necessary. bm and amsfonts are no more required when unicode-math. Indeed, this package is useful to typeset math using a TTF or OTF fonts in particular by default it uses latinmodern-math. bm is a package to get bold glyph in math mode, but with unicode-math you can get the same thing using \symbf that is different from \mathbf. The former typesets a glyph using Unicode code point from the math block of latinmoden-math that is bold I mean a "MATHEMATICAL BOLD". The latter typesets a glyph using the serif text font I mean using a different weight.
Well, Sphinx loads |
|
Sorry for the initial negative response @miticollo, you're right in that even if we don't want to build the pdf docs, we should at least maintain our If you understandably don't want to continue, I hope you don't mind if I push these changes. Thanks. |
|
@lucyleeow This PR is closed because I renamed its branch. I will open a new PR from this new branch. This partially solves three of that six issues that previously you had to solve manually. Futhermore, I improved math. This is possible because doc in HTML version use MathJax to typeset math. I can't read whole doc and fix all issues but I will fix or improve all parts that I will read. For example I noticed that there is an issue with the probability operator. The right operator in LaTeX is |
What does this implement/fix? Explain your changes.
This PR lets successfully build documentation using LuaLaTeX. So it is possible to export documentation in PDF. Details are reported in the body of commits.
Please note, that this PR is a starting point. Many customization are possible like choosing a different text font. Furthermore, a clean up and a code review could be required. I mean Sphinx is useful, but it's not like a human when it "translates" code to TeX.
Here the output PDF.