Sphinx LaTeX PDF documentation bundle

[weiji14]

Description of the desired feature

I have a friend who will be working remotely in the field (Antarctica) without internet access for a few weeks, and he asked me about a PDF copy of the documentation. Upstream GMT has dropped PDF builds in GMT v6.0 as mentioned in https://forum.generic-mapping-tools.org/t/gmt-6-install-complete-documentation-fails/251/2 and GenericMappingTools/gmt#805, but I think we could have it for PyGMT through sphinx's LaTeX PDF build, similar to what other Python packages do on readthedocs.

A few suggestions:

1. Add a make latexpdf option to https://github.com/GenericMappingTools/pygmt/blob/v0.5.0/doc/Makefile so that people can build the PDF locally for any version.
2. Build an official PDF only for each release, and have it as a downloadable release asset somewhere:
   • On the sidebar at https://www.pygmt.org
   • On https://github.com/GenericMappingTools/pygmt/releases
   • On Zenodo maybe?

Here's a PDF I managed to build locally for v0.5.0: pygmt_v0.5.0_docs.pdf. It contains 465 pages and is ~13MB, including all the gallery examples, tutorials and API docs. The commands I ran locally were:

cd ~/path/to/pygmt/doc
make all  # build the API docs
PYGMT_USE_EXTERNAL_DISPLAY="false" sphinx-build -b latex -d _build/doctrees -j auto . _build/latex
cd _build/latex/
make  # build the LaTeX PDF docs

There were a few errors related to missing LaTeX fonts (e.g. I had to do sudo apt install latex-gyre), unicode characters (all the emojis in the changelog 😅) and SVG images (the DOI badges are SVG) which I had to skip through. It should be possible to work out those issues though with a bit of effort.

References:

• https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build
• https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder
• https://github.com/sphinx-doc/sphinx/blob/9e1b4a8f1678e26670d34765e74edf3a3be3c62c/sphinx/templates/quickstart/Makefile_t#L55-L60
• https://sudonull.com/post/70830-How-to-make-LaTeX-and-PDF-generation-in-Sphinx

Are you willing to help implement and maintain this feature? Yes, but want to see if there's demand for it, and whether to do just (1) or both (1) and (2).

[maxrjones]

I expect that there would be demand for this. I would be open to both (1) and (2) if the second could be automated so that it doesn't require extra effort during the release process.

[weiji14]

I expect that there would be demand for this. I would be open to both (1) and (2) if the second could be automated so that it doesn't require extra effort during the release process.

Yep, definitely worth automating this. We can have a GitHub Actions workflow similar to https://github.com/GenericMappingTools/pygmt/blame/v0.5.0/.github/workflows/release-baseline-images.yml created in #1317 that uploads the PDF docs each time a release is made. Could also look at the source code at https://docs.readthedocs.io/en/stable/downloadable-documentation.html to see how the readthedocs people do it.

[seisman]

We have provided a PDF version of the PyGMT documentation for anyone interested. The PDF documentation is automatically built for the main branch by the ReadTheDocs services, so errors in the PDF documentation are expected. We may build a better PDF version in the future if it's highly demanded.

The PDF documentation is available at https://pygmt-dev.readthedocs.io/_/downloads/en/latest/pdf/.

[seisman]

I plan to work on this issue in the next few weeks and hopefully can finish in v0.15.0. Here are the planned changes

• Simplify the doc/Makefile file with sphinx-build's make-mode Simplify doc/Makefile with sphinx-build make-mode #3761
• Add the latex make target to generate LaTeX files. We'll use tectonic to build the LaTeX source files instead of using sphinx's latexpdf builder Simplify doc/Makefile with sphinx-build make-mode #3761
• Add a separate make target (maybe just pdf) to build PDF using tectonic CI: Build PDF documentation using tectonic #3765
• Update the ci_docs.yml workflow to build PDF using tectonic CI: Build PDF documentation using tectonic #3765
• Update the ci_docs.yml workflow to deploy the PDF to gh-pages branch CI: Deploy documentation HTML ZIP archive and PDF file for dev versions #3794
• Update the workflow to upload the PDF when making a release CI: Upload documentation HTML ZIP archive and PDF file as release assets #3814
• Disable the PDF build in ReadTheDocs. CI: Disable building PDF documentation in ReadTheDocs #3812

[seisman]

The PDF documentation for the dev version is available at https://www.pygmt.org/dev/pygmt-docs.pdf.

• Update the workflow to upload the PDF when making a release

Will be tracked in #3731. Done in #3814.

I'm closing the issue and will open a separate issue for tracking the PDF documentation issues mentioned in #3765 (review).