Trying this out, I get an error

 Package fontenc Error: Encoding file `lgrenc.def' not found

Do I have to update something in my latex/tex installation (on Ubuntu 18.04)?

Trying this out, I get an error

 Package fontenc Error: Encoding file `lgrenc.def' not found

@mattip The preamble which this PR activates contained the \usepackage[LGR,T1]{fontenc} which tries to load file lgrenc.def.

Additionally documentation of latex_elements['fontenc'] now says

(copied from Sphinx doc)

Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math mark-up. This is not the case anymore, and the above (i.e. adding LGR) must be used (only in case of 'pdflatex' engine) if the source contains such Unicode Greek.

On Ubuntu xenial, packages texlive-lang-greek and cm-super (for the latter, only if the 'fontpkg' setting is left to its default) are needed for LGR to work. In place of cm-super one can install smaller cm-super-minimal, but it requires the LaTeX document to execute \usepackage[10pt]{type1ec} before loading fontenc. Thus, use this key with this extra at its start if needed.

(end of copied text)

Do I have to update something in my latex/tex installation (on Ubuntu 18.04)?

Yes, probably... as numpy does not modify 'fontpkg', the instructions above should apply. They cover additional LaTeX packages needed by Sphinx when detecting LGR, in particular substitutefont and textgreek packages.

Usage of this LGR is only in case the text is possibly containing Greek letters. LaTeX math mode is still something else. See the "hint" given at latex_elements['textgreek']. But this is quite possibly irrelevant to numpy docs, so a priori all you have to take care of is to make sure suitable LaTeX dependencies are available as indicated above.

edit: actually the numpy conf.py has

latex_elements = {
    'fontenc': r'\usepackage[LGR,T1]{fontenc}'
}

so this does not come from 'preamble' key as I erroneously indicated. The problem about missing lgrenc.def should have arisen earlier...

ah ok I understand, the error was masked by "batchmode" previously on your system with a missing dependency. I tried with this latex file

\documentclass{article}

\usepackage[LGRR,T1]{fontenc}

\begin{document}
coucou
\end{document}

then

$ pdflatex --interaction batchmode testbatchmode.tex
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode

has no trace of the missing file error but

$ pdflatex --halt-on-error testbatchmode.tex
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./testbatchmode.tex
LaTeX2e <2019-10-01> patch level 3
(/usr/local/texlive/2019/texmf-dist/tex/latex/base/article.cls
Document Class: article 2019/10/25 v1.4k Standard LaTeX document class
(/usr/local/texlive/2019/texmf-dist/tex/latex/base/size10.clo))
(/usr/local/texlive/2019/texmf-dist/tex/latex/base/fontenc.sty

! Package fontenc Error: Encoding file `lgrrenc.def' not found.
(fontenc)                You might have misspelt the name of the encoding.

See the fontenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.104 \ProcessOptions*
                      
!  ==> Fatal error occurred, no output PDF file produced!
Transcript written on testbatchmode.log.

@mattip I was going to suggest possibly dropping LGR but in fact numpy-ref.pdf needs it because of

[425]

! Package inputenc Error: Unicode character γ (U+03B3)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.

With LGR included, the Sphinx 2.0 mechanism triggers in, and package textalpha is used which automatically tells pdflatex not to choke on γ. But then lgrenc.def is a LaTeX dependency, thus texlive-lang-greek and cm-super or cm-super-minimal on Ubuntu (see for the latter my previous quote of Sphinx docs for an extra detail)

thus texlive-lang-greek and cm-super or cm-super-minimal on Ubuntu

Thanks, that solved it. So we should mention that somewhere in our dependencies. I think the how to build docs might be appropriate.

@mattip The problem with such documentation is that it could be non obvious to cover all various Linux distros. Specific Sphinx LaTeX requirements are enumerated here but only mention Ubuntu.

Does it matter between requiring cm-super and cm-super-minimal? If we want to allow the latter then the latex_elements['fontpkg'] should be r'\usepackage[10pt]{type1ec}\usepackage[LGR,T1]{fontenc}'. But cm-super-minimal might be a Debian/Ubuntu thing only (sorry, I have no idea). There does not seem to be at TeXLive level itself an analogous, and I find only cm-super packaging name. On the other hand as there is thus such a TeXLive package cm-super it probably exists in all Linux distros whose LaTeX distribution is based upon upstream TeXLive.

I think it is fine to start with Ubuntu. The important thing is have some kind of indication of installation requirements, then users can adapt them to their build systems. Extra points for working fontenc into the instruction so searching the NumPy documentation for latex or fontenc will guide the user to the new instruction

@mattip ok, before actually pushing a commit to add such user info, one last thing. Is there any potential for Numpy docs becoming populated with Unicode apart from individual Greek or Cyrillic letters? Sphinx since 2.0.0 has built-in automatic support via pdflatex route for those (adding resp. LGR and X2 or T2A to 'fontenc' key) but this does not cover things such as Unicode math glyphs (in plain text). I have submitted a matplotlib PR to help build their PDF docs, and it is mandatory at their project to use 'xelatex' (or 'lualatex') with usage of an OpenType font such as STIX (I chose the XITS fork). Perhaps this would be appropriate in the long term for Numpy as well, and would obsolete our LGR discussion and modifies the LaTeX dependency. PS: I will be offline now for a few hours.

Let's try to keep it simple and only add the support for mathematical symbols for now, we can always revisit this in the future.

About my comments about cm-super please take into account I don't have access to an Ubuntu box with admin rights, I can't install or remove packages for testing. I am copying over information which I established at one point in the past for the purpose of Sphinx maintenance but it may not be accurate. Generally speaking advice is that LaTeX should be installed via TeXLive and not rely on Linux distros packaging of it.

I am copying over information which I established at one point in the past for the purpose of Sphinx maintenance but it may not be accurate

I can check that it works locally on an Ubuntu machine. So we are almost there: just need to change the sphinx version to 2.2 and decide whether to use \\gamma and remove LGR.

and decide whether to use \\gamma and remove LGR.

Is this gamma symbol supposed to be usable by copy-paste or Numpy users use euler_gamma input? Because if rendered via math mode it will give in PDF 𝛾 i.e. Unicode hex point 1d6fe MATHEMATICAL ITALIC SMALL GAMMA.

I we use LGR, the PDF will give (at least in my testing with Skim.app on macos x) via copy paste the same as original in source i.e. γ GREEK SMALL LETTER GAMMA.

Let's just put this in as-is, we can fix up the niggle about the sphinx version and greek rendering in a subsequent PR, since the documentation building directions need some editing cleanup anyway.

Thanks @jfbu, looking forward to more contributions in the future.

@mattip thanks now lunch time :-)