Skip to content

CI: Build PDF documentation using tectonic#3765

Merged
seisman merged 20 commits intomainfrom
doc/tectonic
Feb 6, 2025
Merged

CI: Build PDF documentation using tectonic#3765
seisman merged 20 commits intomainfrom
doc/tectonic

Conversation

@seisman
Copy link
Member

@seisman seisman commented Jan 11, 2025 •
edited
Loading

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
seisman commented Jan 11, 2025
View reviewed changes
.github/workflows/ci_docs.yml Outdated
Comment on lines +120 to +121
imagemagick
tectonic
Copy link
Member Author

@seisman seisman Jan 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

doc/conf.py
"sphinx.ext.intersphinx",
"sphinx.ext.mathjax",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
Copy link
Member Author

@seisman seisman Jan 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sort all extensions alphabetically.

doc/conf.py
Comment on lines +253 to +254
# Configurations for LaTeX
latex_engine = "xelatex"
Copy link
Member Author

@seisman seisman Jan 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 seisman added maintenance Boring but important stuff for the core devs needs review This PR has higher priority and needs review. labels Jan 11, 2025
@seisman seisman modified the milestones: 0.14.1, 0.15.0 Jan 11, 2025
@seisman seisman marked this pull request as ready for review January 11, 2025 11:25
@seisman seisman mentioned this pull request Jan 11, 2025
Closed
seisman
seisman commented Jan 11, 2025
View reviewed changes
@seisman
Copy link
Member Author

seisman commented Jan 11, 2025

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

@seisman seisman removed the needs review This PR has higher priority and needs review. label Jan 12, 2025
@seisman seisman marked this pull request as draft January 12, 2025 06:36
@seisman
Copy link
Member Author

seisman commented Jan 12, 2025

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 seisman added the needs review This PR has higher priority and needs review. label Jan 12, 2025
@seisman seisman marked this pull request as ready for review January 12, 2025 13:01
seisman
seisman commented Jan 13, 2025
View reviewed changes
doc/conf.py
"sphinx_copybutton",
"sphinx_design",
"sphinx_gallery.gen_gallery",
"sphinxcontrib.cairosvgconverter",
Copy link
Member Author

@seisman seisman Jan 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add the sphinxcontrib-svg2pdfconverter extension.

weiji14
weiji14 reviewed Jan 13, 2025
View reviewed changes
Copy link
Member

@weiji14 weiji14 left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)
    image

  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 and others added 2 commits January 13, 2025 09:33
@seisman @weiji14
Use tectonic v2 syntax
ec305d0 
Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
@seisman
Add the pdf target to make help
93a9ac3
@seisman
Copy link
Member Author

seisman commented Jan 13, 2025

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

@seisman seisman requested a review from weiji14 January 26, 2025 09:59
@seisman seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. final review call This PR requires final review and approval from a second reviewer labels Feb 4, 2025
@seisman seisman merged commit c9155d7 into main Feb 6, 2025
11 checks passed
@seisman seisman deleted the doc/tectonic branch February 6, 2025 18:47
This was referenced Feb 8, 2025
Closed
Closed
This was referenced Feb 18, 2025
Merged
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@weiji14 weiji14 Awaiting requested review from weiji14

Assignees

No one assigned

Labels

maintenance Boring but important stuff for the core devs

Projects

None yet

Milestone

0.15.0

Development

Successfully merging this pull request may close these issues.

2 participants

@seisman @weiji14