CI: Build PDF documentation using tectonic

[seisman]

We can use Sphinx's latexpdf builder to build PDFs, but we have to install a TeX distributions (e.g., TeXLive on Linux, MacTeX on macOS), and also related TeX packages (via tlmgr). It means much maintenance burdern.

Instead, we can use Tectonic:

Tectonic is a modernized, complete, self-contained TeX/LaTeX engine, powered by XeTeX and TeXLive.

Why Tectonic:

1. It's a single binary and can be installed from conda-forge
2. It can install TeX packages automatically based on the needs of the documentation.

So, we just need to run

make latex   # Generate LaTeX source files
tectonic path/to/pygmt.tex

Address #1606.

[seisman]

The badges in the documentation are SVG files, and LaTeX doesn't support SVG with errors like:

error: pygmt.tex:52276: LaTeX Error: Cannot determine size of graphic in /home/runner/work/pygmt/pygmt/doc/_build/doctrees/images/455a48e4d8f250af2dc5ad447126b4eeac754d52/zenodo.14535921.svg (no BoundingBox).

The issue can be fixed by enabling the sphinx.ext.imgconverter extension, which requires ImageMagick.

As explained in https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html:

ImageMagick rasterizes a SVG image on conversion. As a result, the image becomes not scalable. To avoid that, please use other image converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape or rsvg-convert).

Here is a comparison for different ways to support SVG in PDFs. From the CI runs, we can know the number of packages, and their sizes for each case:

Option	No. of pkgs	Download size	Cache size	Time to create the env
sphinx.ext.imgconverter + ImageMagick	327	580 MB	632 MB	120 s
sphinxcontrib-svg2pdfconverter + librsvg	315	554 MB	598 MB	60 s
sphinxcontrib-svg2pdfconverter + CairoSVG	316	547 MB	589 MB	60 s

It seems "sphinxcontrib-svg2pdfconverter + CairoSVG" is the preferred option.

[seisman]

Sort all extensions alphabetically.

[seisman]

The default latex engine is pdflatex, and it doens't support Unicode characters well. With latex_engine set to xelatex, Sphinx adds more tex packages (mainly fontenc and supports Unicode better.

[seisman]

The PDF documentation can be downloaded from https://github.com/GenericMappingTools/pygmt/actions/runs/12723811069/artifacts/2416819544.

[seisman]

If you'd like to try to build PDF locally, you can do:

conda activate pygmt
mamba install tectonic sphinxcontrib-svg2pdfconverter cairosvg
cd doc/
make pdf

[seisman]

Add the sphinxcontrib-svg2pdfconverter extension.

[weiji14]

Thanks @seisman, that tectonic package looks awesome, takes so much pain out of installing TeXLive (especially in a cross-platform way)! I've left a few small suggestions for now below, and have three side comments (that can be addressed separately).

1. On the first page, it say 'Author name not set'. It would be nice if we could grab the names from the CITATION.cff file somehow.

2. Missing emojis, unsure if there's anyway to show them in LaTeX (if it involves downloading a large font file, we can skip it)
   

3. In the PDF file, the 'PyGMT Team' section lists everyone's profile pictures on 1 page (at a low-resolution). Unsure if there's a way to make those photos smaller.

Overall, at 649 pages (!!), I hope nobody tries to print this or it'll be a very thick book!

[seisman]

Thanks @seisman, that tectonic package looks awesome, takes so much pain out of installing TeXLive (especially in a cross-platform way)! I've left a few small suggestions for now below, and have two side comments (that can be addressed separately).

1. On the first page, it say 'Author name not set'. It would be nice if we could grab the names from the CITATION.cff file somehow.
2. Missing emojis, unsure if there's anyway to show them in LaTeX (if it involves downloading a large font file, we can skip it)
   
3. In the PDF file, the 'PyGMT Team' section lists everyone's profile pictures on 1 page (at a low-resolution). Unsure if there's a way to make those photos smaller.

Overall, at 649 pages (!!), I hope nobody tries to print this or it'll be a very thick book!

Yes, will try to address the PDF issues in future PRs.