iiasa / iiasa/message_ix

Building PDF version of the docs from LaTeX fails locally

Open
#722 1 comment 1 reaction 0 assignees View on GitHub
bug docs
Dominant language
Jupyter Notebook
Stars
150
Forks
178
Avg merge
17h 32m
Merged PRs (30d)
2

Description

#### 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`:

```bash
! 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`:

```bash
! String contains an invalid utf-8 sequence.

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](https://iiasa-ece.slack.com/archives/D04K2V3HHLY/p1687428104021929), this is fine (also tried removing brackets manually). Adjusting the `doc/conf.py` to read
```python
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
```bash
LaTeX Warning: Hyper reference `contributing::doc' on page 5 undefined on input
line 452.
```
And things like
```bash
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
```bash
------------
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.

Contributor guide

Open the contributing guide

Research direction

Start in doc/ with the make latex target, then inspect the generated _build/latex files and doc/conf.py. Compare the failures from make all-pdf and latexmk messageix.tex, including the hyperref and invalid UTF-8 errors. Done means the documentation builds successfully as one shareable PDF.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, python
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.