CI: Build PDF documentation using tectonic (#3765)

Co-authored-by: Wei Ji <[email protected]>

.github/workflows/ci_docs.yml

@@ -117,6 +117,9 @@ jobs:
             sphinx-design
             sphinx-gallery
             sphinx_rtd_theme<3.0
+            cairosvg
+            sphinxcontrib-svg2pdfconverter
+            tectonic
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
@@ -135,9 +138,11 @@ jobs:
           python -m build --sdist
           python -m pip install dist/*
 
-      # Build the documentation
-      - name: Build the documentation
-        run: make -C doc clean all
+      - name: Build the HTML documentation
+        run: make -C doc clean html
+
+      - name: Build the PDF documentation
+        run:  make -C doc pdf
 
       - name: Checkout the gh-pages branch
         uses: actions/[email protected]

ci/requirements/docs.yml

@@ -32,3 +32,6 @@ dependencies:
     - sphinx-design
     - sphinx-gallery
     - sphinx_rtd_theme<3.0
+    # Dev dependencies (building PDF documentation)
+    # 'sphinxcontrib-svg2pdfconverter' is required since it's added to `extensions`.
+    - sphinxcontrib-svg2pdfconverter

doc/Makefile

@@ -15,6 +15,7 @@ help:
 	@echo "  api          generate rst source files of API documentation"
 	@echo "  html         build the HTML files from the existing rst sources"
 	@echo "  html-noplot  build the HTML files without running any examples"
+	@echo "  pdf          build the PDF documentation"
 	@echo "  server       make a local HTTP server for previewing the built documentation"
 	@echo "  clean        clean up built and generated files"
 
@@ -43,6 +44,14 @@ html-noplot: api
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+pdf: latex
+	@echo
+	@echo "Building PDF via Tectonic."
+	@echo
+	tectonic -X compile $(BUILDDIR)/latex/pygmt.tex
+	@echo
+	@echo "PDF build finished. The PDF file is in $(BUILDDIR)/latex/pygmt.pdf."
+
 server:
 	@echo
 	@echo "Running a server on port 8009."

doc/conf.py

@@ -28,16 +28,17 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
-    "sphinx.ext.mathjax",
     "sphinx.ext.doctest",
-    "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
+    "sphinxcontrib.cairosvgconverter",
 ]
 
 # Suppress warnings
@@ -248,3 +249,6 @@
     "github_version": "main",
     "commit": commit_link,
 }
+
+# Configurations for LaTeX
+latex_engine = "xelatex"

environment.yml

@@ -44,6 +44,10 @@ dependencies:
     - sphinx-design
     - sphinx-gallery>=0.17.0
     - sphinx_rtd_theme<3.0
+    # Dev dependencies (building PDF documentation)
+    - cairosvg
+    - sphinxcontrib-svg2pdfconverter
+    - tectonic
     # Dev dependencies (type hints)
     - mypy
     - pandas-stubs