Building PDF version of the docs from LaTeX fails locally

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.

------------
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.

iiasa / message_ix