Skip to content

CI: Build PDF documentation using tectonic #3765

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

Merged
merged 20 commits into from
Feb 6, 2025
Merged

CI: Build PDF documentation using tectonic #3765

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
20 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
913c9ec
Merge branch 'main' into doc/tectonic
seisman Feb 3, 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
11 changes: 8 additions & 3 deletions .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,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
Expand All @@ -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]
Expand Down
3 changes: 3 additions & 0 deletions ci/requirements/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
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
@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."
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,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",
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",
"sphinx_gallery.gen_gallery",
"sphinxcontrib.cairosvgconverter",
Copy link
Member Author

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.

]

# Suppress warnings
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.

4 changes: 4 additions & 0 deletions environment.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading