From 050ab216d372eae50cb609dc96761722d06d6fab Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 14:20:53 +0800 Subject: [PATCH 01/15] CI: Build PDF documentation using tectonic --- .github/workflows/ci_docs.yml | 11 ++++++++++- doc/Makefile | 8 ++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 06c7debb426..4c3968173c5 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -117,6 +117,7 @@ jobs: sphinx-design sphinx-gallery sphinx_rtd_theme<3.0 + tectonic # Download cached remote files (artifacts) from GitHub - name: Download remote data from GitHub @@ -137,7 +138,15 @@ jobs: # Build the documentation - name: Build the documentation - run: make -C doc clean all + run: make -C doc clean html pdf + + # Temporarily upload the built PDF to the artifacts + - name: Upload PDF to artifacts + uses: actions/upload-artifact@v4.5.0 + with: + name: pygmt-docs-pdf + path: doc/_build/latex/pygmt.pdf + if: matrix.os == 'ubuntu-latest' - name: Checkout the gh-pages branch uses: actions/checkout@v4.2.2 diff --git a/doc/Makefile b/doc/Makefile index 5656fe80ab6..19833aa8685 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -43,6 +43,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 $(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." From 755505c427af347aebdfbd17f012295b11c42ccb Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 15:05:36 +0800 Subject: [PATCH 02/15] Enable the sphinx.ext.imgconverter extension --- doc/conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index f3cb59228c2..a2cbcce1e3b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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", "sphinx_autodoc_typehints", "sphinx_copybutton", "sphinx_design", From 077bfb2257ff53fa7d871867aa6e907a8ea1d7cf Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 15:55:39 +0800 Subject: [PATCH 03/15] Check the files in the _build/latex directory --- .github/workflows/ci_docs.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 4c3968173c5..7078af5a6f6 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -138,7 +138,12 @@ jobs: # Build the documentation - name: Build the documentation - run: make -C doc clean html pdf + 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 From e7d81e709fe7fd790879ce83f5177b64d8e0632f Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 16:18:02 +0800 Subject: [PATCH 04/15] Add ImageMagick needed by the sphinx.ext.imgconverter extension --- .github/workflows/ci_docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 7078af5a6f6..c98dd706994 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -117,6 +117,7 @@ jobs: sphinx-design sphinx-gallery sphinx_rtd_theme<3.0 + imagemagick tectonic # Download cached remote files (artifacts) from GitHub From cf0006ec89e051f15febd8362259f36dd619f216 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 17:09:29 +0800 Subject: [PATCH 05/15] Set the default latex engine to xelatex --- doc/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index a2cbcce1e3b..ec440da60e7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -249,3 +249,6 @@ "github_version": "main", "commit": commit_link, } + +# Configurations for LaTeX +latex_engine = "xelatex" From e6270efb503c35243abd8ebbb1ed348ab447d7ab Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 17:21:59 +0800 Subject: [PATCH 06/15] No need to list the files anymore --- .github/workflows/ci_docs.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index c98dd706994..7ce7beb471c 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -142,9 +142,7 @@ jobs: run: make -C doc clean html - name: Build the PDF - run: | - make -C doc pdf - ls -lh doc/_build/latex/* + run: make -C doc pdf # Temporarily upload the built PDF to the artifacts - name: Upload PDF to artifacts From 225d46e9d811c4f05c01df5e8bd0d9f3bac9e108 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 17:45:49 +0800 Subject: [PATCH 07/15] Add the packages to environment.yml --- environment.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/environment.yml b/environment.yml index c51b2967fc2..af36e6340ec 100644 --- a/environment.yml +++ b/environment.yml @@ -44,6 +44,9 @@ dependencies: - sphinx-design - sphinx-gallery>=0.17.0 - sphinx_rtd_theme<3.0 + # Dev dependencies (building PDF documentation) + - imagemagick + - tectonic # Dev dependencies (type hints) - mypy - pandas-stubs From 54406c088b38be44c14b33d5108c670a487f0183 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 18:19:36 +0800 Subject: [PATCH 08/15] Try sphinxcontrib-svg2pdfconverter + librsvg --- .github/workflows/ci_docs.yml | 3 ++- doc/conf.py | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 7ce7beb471c..de291a33bc7 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -117,7 +117,8 @@ jobs: sphinx-design sphinx-gallery sphinx_rtd_theme<3.0 - imagemagick + librsvg + sphinxcontrib-svg2pdfconverter tectonic # Download cached remote files (artifacts) from GitHub diff --git a/doc/conf.py b/doc/conf.py index ec440da60e7..8e95c4081cd 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -30,7 +30,6 @@ "sphinx.ext.coverage", "sphinx.ext.doctest", "sphinx.ext.extlinks", - "sphinx.ext.imgconverter", "sphinx.ext.intersphinx", "sphinx.ext.mathjax", "sphinx.ext.napoleon", @@ -39,6 +38,7 @@ "sphinx_copybutton", "sphinx_design", "sphinx_gallery.gen_gallery", + "sphinxcontrib.rsvgconverter", ] # Suppress warnings From e780d43f66e60cecea78eb09d271eef90953afaa Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 18:29:05 +0800 Subject: [PATCH 09/15] Try sphinxcontrib-svg2pdfconverter + CairoSVG --- .github/workflows/ci_docs.yml | 2 +- doc/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index de291a33bc7..ee622bcfd87 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -117,7 +117,7 @@ jobs: sphinx-design sphinx-gallery sphinx_rtd_theme<3.0 - librsvg + cairosvg sphinxcontrib-svg2pdfconverter tectonic diff --git a/doc/conf.py b/doc/conf.py index 8e95c4081cd..4c6d23b9a05 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -38,7 +38,7 @@ "sphinx_copybutton", "sphinx_design", "sphinx_gallery.gen_gallery", - "sphinxcontrib.rsvgconverter", + "sphinxcontrib.cairosvgconverter", ] # Suppress warnings From c85c571412d3fa6fd91f581918c6fedaf3ef4781 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 11 Jan 2025 18:52:32 +0800 Subject: [PATCH 10/15] Use sphinxcontrib-svg2pdfconverter + cairosvg --- ci/requirements/docs.yml | 4 ++++ environment.yml | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/ci/requirements/docs.yml b/ci/requirements/docs.yml index 2a6fa860961..4a4c4ef129e 100644 --- a/ci/requirements/docs.yml +++ b/ci/requirements/docs.yml @@ -32,3 +32,7 @@ dependencies: - sphinx-design - sphinx-gallery - sphinx_rtd_theme<3.0 + # Dev dependencies (building PDF documentation) + - cairosvg + - sphinxcontrib-svg2pdfconverter + - tectonic diff --git a/environment.yml b/environment.yml index af36e6340ec..616be8a8318 100644 --- a/environment.yml +++ b/environment.yml @@ -45,7 +45,8 @@ dependencies: - sphinx-gallery>=0.17.0 - sphinx_rtd_theme<3.0 # Dev dependencies (building PDF documentation) - - imagemagick + - cairosvg + - sphinxcontrib-svg2pdfconverter - tectonic # Dev dependencies (type hints) - mypy From 8d1b14a05f5d9aa1eeecbc3226c533f6585f66ca Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 12 Jan 2025 14:35:13 +0800 Subject: [PATCH 11/15] Upload PDF as artifacts so that we can deploy it later --- .github/workflows/ci_docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index ee622bcfd87..25692b1ed58 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -145,7 +145,6 @@ jobs: - name: Build the PDF run: make -C doc pdf - # Temporarily upload the built PDF to the artifacts - name: Upload PDF to artifacts uses: actions/upload-artifact@v4.5.0 with: From 535da8fb62fdbef88dc4357bb167f52013564ab2 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 12 Jan 2025 20:50:32 +0800 Subject: [PATCH 12/15] Remove the 'Upload PDF to artifacts' step --- .github/workflows/ci_docs.yml | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 25692b1ed58..344e0a602bf 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -138,20 +138,12 @@ jobs: python -m build --sdist python -m pip install dist/* - # Build the documentation - - name: Build the documentation + - name: Build the HTML documentation run: make -C doc clean html - - name: Build the PDF + - name: Build the PDF documentation run: make -C doc pdf - - name: Upload PDF to artifacts - uses: actions/upload-artifact@v4.5.0 - with: - name: pygmt-docs-pdf - path: doc/_build/latex/pygmt.pdf - if: matrix.os == 'ubuntu-latest' - - name: Checkout the gh-pages branch uses: actions/checkout@v4.2.2 with: From 32011fe7338688a5992f4aba6c5c3a96b101019e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 12 Jan 2025 20:59:27 +0800 Subject: [PATCH 13/15] Remove two packages not needed on ReadTheDocs --- ci/requirements/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ci/requirements/docs.yml b/ci/requirements/docs.yml index 4a4c4ef129e..5a233e36c80 100644 --- a/ci/requirements/docs.yml +++ b/ci/requirements/docs.yml @@ -33,6 +33,5 @@ dependencies: - sphinx-gallery - sphinx_rtd_theme<3.0 # Dev dependencies (building PDF documentation) - - cairosvg + # 'sphinxcontrib-svg2pdfconverter' is required since it's added to `extensions`. - sphinxcontrib-svg2pdfconverter - - tectonic From ec305d01f0e23dccda8876298284130d6bc27564 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 13 Jan 2025 09:33:19 +0800 Subject: [PATCH 14/15] Use tectonic v2 syntax Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index 36676b70ef7..734bcb3faf7 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -47,7 +47,7 @@ pdf: latex @echo @echo "Building PDF via Tectonic." @echo - tectonic $(BUILDDIR)/latex/pygmt.tex + tectonic -X compile $(BUILDDIR)/latex/pygmt.tex @echo @echo "PDF build finished. The PDF file is in $(BUILDDIR)/latex/pygmt.pdf." From 93a9ac377f47850e9483fb7005e3cf64725304c0 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 13 Jan 2025 09:35:09 +0800 Subject: [PATCH 15/15] Add the pdf target to make help --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile b/doc/Makefile index 734bcb3faf7..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"