From c9155d75911add25132201853c22d38af1896587 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 7 Feb 2025 02:47:43 +0800 Subject: [PATCH] CI: Build PDF documentation using tectonic (#3765) Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- .github/workflows/ci_docs.yml | 11 ++++++++--- ci/requirements/docs.yml | 3 +++ doc/Makefile | 9 +++++++++ doc/conf.py | 8 ++++++-- environment.yml | 4 ++++ 5 files changed, 30 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index b02d953c0f7..2d9ebe31907 100644 --- a/.github/workflows/ci_docs.yml +++ b/.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/checkout@v4.2.2 diff --git a/ci/requirements/docs.yml b/ci/requirements/docs.yml index 2a6fa860961..5a233e36c80 100644 --- a/ci/requirements/docs.yml +++ b/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 diff --git a/doc/Makefile b/doc/Makefile index 04b1c1ab549..ea146705463 100644 --- a/doc/Makefile +++ b/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." diff --git a/doc/conf.py b/doc/conf.py index 58d4380020b..91f032adb71 100644 --- a/doc/conf.py +++ b/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" diff --git a/environment.yml b/environment.yml index c51b2967fc2..616be8a8318 100644 --- a/environment.yml +++ b/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