Building PDF version of the docs from LaTeX fails locally

[glatterf42]

Code sample or context

After cloning the repository and changing to doc/, make latex works fine (i.e. finishes with just a few warnings), but changing to the created _build/latex and running make all-pdf fails with several hundred errors. Running this command is weirdly abridged so that the error messages are not always clearly visible. This can partly be remedied by running latexmk messageix.tex instead, though that seems to cause a different error message. Unfortunately, chaning the latex_engine from lualatex to xelatex did not help.

Expected result

The docs should be built successfully as a single PDF file which could then easily be shared.

Problem description

The build process stops with the following message and asks about what it should do with it. Running make all-pdf:

! Undefined control sequence.
\hyper@@link ->\let \Hy@reserved@a 
                                   \relax \@ifnextchar [{\hyper@link@ }{\hyp...
l.544 ...asis{ix} mathematical model formulation.}
                                                  \label{\detokenize{framewo...

?

Running latexmk messageix.tex:

! String contains an invalid utf-8 sequence.
<read 0> 
   PNG
l.545 ...nt\sphinxincludegraphics{{ix_components}.png}
                                                  
?

My first guess was that the double {{ might cause the error here, but as per explanation in this Slack thread, this is fine (also tried removing brackets manually). Adjusting the doc/conf.py to read

latex_elements = {
    "maxlistdepth": 10,
    "preamble": r"""\usepackage{unicode-math}
\usepackage{graphicx}""",
}

did not help, neither did manually including the hyperref package. It is very unlikely that this is due to my tex installation as this is up-to-date and a test build on a different system (thanks, @Findus23) did not work either.

Notably, we have set on ReadTheDocs that a PDF and EPUB version should be created with each build. However, I cannot find any PDF build logs or available for download newer than of version 2.0.0.

For completeness' sake, there are also several warnings of the sort

LaTeX Warning: Hyper reference `contributing::doc' on page 5 undefined on input
 line 452.

And things like

Package hyperref Warning: You have enabled option `breaklinks'.
(hyperref)                But driver `hdvips.def' does not suppport this.
(hyperref)                Expect trouble with the link areas of broken links.

or

------------
Run number 1 of rule 'latex'
------------
------------
Running 'lualatex --output-format=dvi   -recorder  "messageix.tex"'
------------
This is LuaHBTeX, Version 1.17.0 (TeX Live 2023) 
 restricted system commands enabled.
(./messageix.tex
LaTeX2e <2023-06-01> patch level 1
L3 programming layer <2023-06-16>
 (/usr/local/texlive/2023/texmf-dist/tex/generic/luatex85/luatex85.sty)
(./sphinxmanual.cls
Document Class: sphinxmanual 2019/12/01 v2.3.0 Document class (Sphinx manual)
(/usr/local/texlive/2023/texmf-dist/tex/latex/base/report.cls
Document Class: report 2023/05/17 v1.4n Standard LaTeX document class
(/usr/local/texlive/2023/texmf-dist/tex/latex/base/size10.clo)))
(/usr/local/texlive/2023/texmf-dist/tex/latex/cmap/cmap.sty

Package cmap Warning: pdftex in DVI mode - exiting.

) (/usr/local/texlive/2023/texmf-dist/tex/latex/fontspec/fontspec.sty

Versions

Output of message-ix show-versions

message_data is not installed or cannot be imported

ixmp:        3.7.1.dev0+gf348a6b.d20230526
     8a680d1 (HEAD -> update/rtd-config, origin/update/rtd-config) Rename config file, require extra [docs]
message_ix:  3.7.1.dev13+geb940c4
     aed572e (HEAD -> fix/latex-core) Include textmacros package; start rewriting \text{*\_*} to enable latexpdf
message_ix_models: 2023.4.3.dev9+g3ded82f
     2c685e3 (HEAD -> enh/zenodo-snapshot, origin/enh/zenodo-snapshot) Improve doc/model-snapshot per @glatterf42 review comment
message_data: None

click:       8.1.3
dask:        2022.12.1
genno:       installed
graphviz:    0.20.1
jpype:       1.4.0
… JVM path:  /usr/lib/jvm/java-19-openjdk-amd64/lib/server/libjvm.so
openpyxl:    3.0.10
pandas:      1.5.2
pint:        0.22.dev27+g2a89a44
xarray:      2022.12.0
yaml:        6.0

iam_units:   installed
jupyter:     1.0.0
matplotlib:  3.6.3
plotnine:    0.10.1
pyam:        1.7.0

GAMS:        41.5.0

python:      3.10.6 (main, May 29 2023, 11:10:38) [GCC 11.3.0]
python-bits: 64
OS:          Linux
OS-release:  5.19.0-45-generic
machine:     x86_64
processor:   x86_64
byteorder:   little
LC_ALL:      None
LANG:        en_US.UTF-8
LOCALE:      ('en_US', 'UTF-8')

Conclusion

Having spent the last two days hunting these errors unsuccessfully, I have come to doubt that anyone is missing the option to build the LaTeX-PDF locally. If it was missing, there would have been more support requests for exactly that over the last three years. For the time being, I will therefore stop this project.
If you are missing this option, please let us know by upvoting this issue and updating it with information on your system and the error messages you receive.

[glatterf42]

The supported image types for the sphinx LaTeXBuilder include both PNG and PDF despite the sphinx image docs claiming that LaTeX prefers PDF over PNG. Either way, we are also trying to include JPG, WEBP, and SVG files, which do not seem to be supported by LaTeX in sphinx. Note that when providing multiple formats of the same image, including it as image_name.* allows sphinx to choose the format it prefers for the current builder. Also note that the only directive allows you to write code that is used only for LaTeX or only for HTML.

In the past, some people reported having to follow a certain order in which LaTeX packages are imported. However, moving all of the packages that are reported after hyperref by us manually before it (one by one) did not change anything (those were sphinxmessages, unicode-math, and graphicx). This problem might also be about expansion but I'm not aware of any config settings there and we are not manually adding expansion commands where we should not.

For good measure, find here the sphinx docs on LaTeX customization.