Convincing Documenter to create a PDF output

Tooling
1

I’m trying to get Documenter to create a PDF version of my package’s docs. Following the documentation, I first tried makedocs(format = Documenter.LaTeX())… but quickly realized I no longer have a TeX installation. Duh.

[ Info: LaTeXWriter: creating the LaTeX file.
┌ Error: LaTeXWriter: latexmk command not found.
└ @ Documenter.Writers.LaTeXWriter ~/.julia/packages/Documenter/tBpqI/src/Writers/LaTeXWriter.jl:180
ERROR: LoadError: Compiling the .tex file failed. See logs for more information.

Ah, but the tectonic_jll looks like an easy answer. But I hit the next roadblock:

[ Info: LaTeXWriter: using tectonic to compile tex.
┌ Error: LaTeXWriter: failed to compile tex with tectonic. Logs and partial output can be found in /var/folders/t2/6mc816z13z561xv9r6rdw84c0000gn/T/jl_m4bFT4.

Digging in that logs file reveals that I didn’t have DejaVu Sans and DejaVu Mono installed. Ah, yes, that’s on the documentation, too… ok, downloaded from https://dejavu-fonts.github.io…

But then I hit the problem that I don’t have the pygmentize/minted package installed. And now I’m stuck: How do I install a package from CTAN with tectonic_jll?

In the logs I got:

! Package minted Error: You must have `pygmentize' installed to use this packag
e.
2

LaTex is hard to install from individual packages. I usually just install a big TeXLive install, and through that you can get all the fonts, packages, etc…

https://www.tug.org/texlive/

3

In case you need inspiration, @odow did this for (the fairly complex) documentation in JuMP:
https://github.com/jump-dev/JuMP.jl/pull/2760/files

2 Likes
4

On CI, as in the JuMP example, using the Docker platform (format = Documenter.LaTeX(platform = "docker") is the easiest option, as that pulls a Docker image that has all the necessary dependencies. You can also use it locally if you have Docker installed.

For the Tectonic issue… I believe it should download the TeX dependencies automatically…? So is it the Python package that is missing? On Linux, that should be available via the package manager (e.g. apt install python-pygments or something like that).

1 Like
5

Oooh, I see, it’s not a TeX package I need, but rather it’s that the TeX package minted (which is in that tectonic distribution) needs pygmentize, which comes from a Python package. Is it looking for a pygmentize executable to be on my PATH?

6

Yep. It’s in the pygments package.

I have just learned about tectonic from this thread. Seems great for any situation where you need to TeX something fast or in containers/CI, but the absence of proper package management makes me a bit skeptical if I would replace my TeXLive on my main system with it.

7

Hm, ok, I actually do have pigmentize installed… in my Julia-managed conda folder. How do I get tectonic to see this?

$ PATH="~/.julia/conda/3/bin:$PATH" julia --project -q
shell> pygmentize --help
Usage: /Users/mbauman/.julia/conda/3/bin/pygmentize [-l <lexer> | -g] [-F <filter>[:<options>]] [-f <formatter>]
          [-O <options>] [-P <option=value>] [-s] [-v] [-x] [-o <outfile>] [<infile>]

# ...

julia> include("docs/make.jl")
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: LaTeXWriter: creating the LaTeX file.
[ Info: LaTeXWriter: using tectonic to compile tex.
┌ Error: LaTeXWriter: failed to compile tex with tectonic. Logs and partial output can be found in /var/folders/t2/6mc816z13z561xv9r6rdw84c0000gn/T/jl_vsMvVD.
│   exception =
│    failed process: Process(#=...=#) [1]
│
└ @ Documenter.Writers.LaTeXWriter ~/.julia/packages/Documenter/tBpqI/src/Writers/LaTeXWriter.jl:200
ERROR: LoadError: Compiling the .tex file failed. See logs for more information.

And the logs show the same:

! Package minted Error: You must have `pygmentize' installed to use this packag
e.

See the minted package documentation for explanation.
8

Huh. Worked for me out of the box with pygments installed via conda on Windows with
format = Documenter.LaTeX(platform="tectonic", tectonic=tectonic())

Does the tectonic command have the conda/bin path in its environment?

using tectonic_jll

tectonic()
9

Yep:

$ PATH="~/.julia/conda/3/bin:$PATH" julia --project -q
julia> using tectonic_jll

julia> tectonic().env[1]
"PATH=/Users/mbauman/.julia/artifacts/3bb83a2812f716f0d1610026d1e470dbf92a952e/bin:/Users/mbauman/.julia/artifacts/2cb0d96a63120d1a0868c905452895a59add9a0d/bin:/Users/mbauman/.julia/artifacts/177d0c3c85c9de270494ca5bb483d7a6d15b3ee8/bin:/Users/mbauman/.julia/artifacts/fce62671858920d3556be53bfdb2604f9dd979c6/bin:/Users/mbauman/.julia/artifacts/9dc7efd1fa13f0fae6d824676bd2f8beabc4c99e/bin:~/.julia/conda/3/bin:/Users/mbauman/bin:/Users/mbauman/.dotfiles/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin"

Maybe it doesn’t like tildes in the PATH? AHA! Yep:

$ PATH="/Users/mbauman/.julia/conda/3/bin:$PATH" julia --project -q
julia> include("docs/make.jl")
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: LaTeXWriter: creating the LaTeX file.
[ Info: LaTeXWriter: using tectonic to compile tex.

julia>

Success! Thanks everyone!

3 Likes