Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CI: Build PDF documentation using tectonic #3765

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
Open

CI: Build PDF documentation using tectonic #3765

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
050ab21
CI: Build PDF documentation using tectonic
seisman Jan 11, 2025
755505c
Enable the sphinx.ext.imgconverter extension
seisman Jan 11, 2025
077bfb2
Check the files in the _build/latex directory
seisman Jan 11, 2025
e7d81e7
Add ImageMagick needed by the sphinx.ext.imgconverter extension
seisman Jan 11, 2025
cf0006e
Set the default latex engine to xelatex
seisman Jan 11, 2025
e6270ef
No need to list the files anymore
seisman Jan 11, 2025
225d46e
Add the packages to environment.yml
seisman Jan 11, 2025
54406c0
Try sphinxcontrib-svg2pdfconverter + librsvg
seisman Jan 11, 2025
e780d43
Try sphinxcontrib-svg2pdfconverter + CairoSVG
seisman Jan 11, 2025
c85c571
Use sphinxcontrib-svg2pdfconverter + cairosvg
seisman Jan 11, 2025
510b269
Merge branch 'main' into doc/tectonic
seisman Jan 12, 2025
8d1b14a
Upload PDF as artifacts so that we can deploy it later
seisman Jan 12, 2025
535da8f
Remove the 'Upload PDF to artifacts' step
seisman Jan 12, 2025
32011fe
Remove two packages not needed on ReadTheDocs
seisman Jan 12, 2025
06d668f
Merge branch 'main' into doc/tectonic
seisman Jan 13, 2025
ec305d0
Use tectonic v2 syntax
seisman Jan 13, 2025
93a9ac3
Add the pdf target to make help
seisman Jan 13, 2025
5a7390d
Merge branch 'main' into doc/tectonic
seisman Jan 17, 2025
c844c5a
Merge branch 'main' into doc/tectonic
seisman Jan 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion .github/workflows/ci_docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ jobs:
sphinx-design
sphinx-gallery
sphinx_rtd_theme<3.0
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.


# Download cached remote files (artifacts) from GitHub
- name: Download remote data from GitHub
Expand All @@ -137,7 +139,20 @@ jobs:

# Build the documentation
- name: Build the documentation
run: make -C doc clean all
run: make -C doc clean html

- name: Build the PDF
run: |
make -C doc pdf
ls -lh doc/_build/latex/*

# Temporarily upload the built PDF to the artifacts
- name: Upload PDF to artifacts
uses: actions/[email protected]
with:
name: pygmt-docs-pdf
path: doc/_build/latex/pygmt.pdf
if: matrix.os == 'ubuntu-latest'
seisman marked this conversation as resolved.
Show resolved Hide resolved

- name: Checkout the gh-pages branch
uses: actions/[email protected]
Expand Down
8 changes: 8 additions & 0 deletions doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,14 @@ html-noplot: api
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

pdf: latex
seisman marked this conversation as resolved.
Show resolved Hide resolved
@echo
@echo "Building PDF via Tectonic."
@echo
tectonic $(BUILDDIR)/latex/pygmt.tex
seisman marked this conversation as resolved.
Show resolved Hide resolved
@echo
@echo "PDF build finished. The PDF file is in $(BUILDDIR)/latex/pygmt.pdf."

server:
@echo
@echo "Running a server on port 8009."
Expand Down
8 changes: 6 additions & 2 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,13 @@
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.coverage",
"sphinx.ext.mathjax",
"sphinx.ext.doctest",
"sphinx.ext.viewcode",
"sphinx.ext.extlinks",
"sphinx.ext.imgconverter",
"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.

"sphinx_autodoc_typehints",
"sphinx_copybutton",
"sphinx_design",
Expand Down Expand Up @@ -248,3 +249,6 @@
"github_version": "main",
"commit": commit_link,
}

# Configurations for LaTeX
latex_engine = "xelatex"
Comment on lines +253 to +254
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.

Loading