Setting up an environment for PDF output from Sphinx via TeX

Hi, I’m agata.

In our company, we write various documents in Sphinx and build them in Netlify via GitLab so that they can be viewed in a web browser. This is usually sufficient, but it can be a little inconvenient if you need to attach them to an email or output them to paper for various reasons.

Envirnment

As usual, I will assume my environment. My documentation environment is as follows.

• MacBook
• macOS High Sierra (10.13.6)
• Homebrew 2.0.4
  • Homebrew/homebrew-core (git revision a290; last commit 2019-03-16)
  • Homebrew/homebrew-cask (git revision 3db818; last commit 2019-03-17)
• Sphinx 1.8.0

Installing TeX

To generate PDFs from Sphinx, you need to go through TeX. For this reason, a TeX processing environment is required; on macOS, this can be easily installed using Homebrew.

$ brew cask install mactex

Depending on the environment, it can take quite a long time due to the large size of the TeX package. Take your time and wait.

==> Satisfying dependencies
 ==> Installing Formula dependencies: ghostscript
 ==> Installing dependencies for ghostscript: libtiff
 ==> Installing ghostscript dependency: libtiff
 ==> Downloading https://homebrew.bintray.com/bottles/libtiff-4.0.10_1.high_sierra.bottle.tar.gz
 ################################################################## 100.0%
 ==> Pouring libtiff-4.0.10_1.high_sierra.bottle.tar.gz
 ?  /usr/local/Cellar/libtiff/4.0.10_1: 246 files, 3.5MB
 ==> Installing ghostscript
 ==> Downloading https://homebrew.bintray.com/bottles/ghostscript-9.26_1.high_sierra.bottle.tar.gz
 ################################################################## 100.0%
 ==> Pouring ghostscript-9.26_1.high_sierra.bottle.tar.gz
 ?  /usr/local/Cellar/ghostscript/9.26_1: 668 files, 81.1MB
 ==> Downloading http://mirror.ctan.org/systems/mac/mactex/mactex-20180417.pkg
 ==> Downloading from ftp://ftp.kddilabs.jp/CTAN/systems/mac/mactex/mactex-20180417.pkg
 ################################################################## 100.0%
 ==> Verifying SHA-256 checksum for Cask 'mactex'.
 ==> Installing Cask mactex
 ==> Running installer for mactex; your password may be necessary.
 ==> Package installers may write to any location; options such as --appdir are ignored.
 Password:

When the mactex installation starts, you will be asked for your password, which you should enter. Again, this will take more time……..

installer: Package name is MacTeX-2018
 installer: choices changes file '/var/folders/tg/lt98nx792tj67l35cv39860c0000gn/T/choices20190317-6954-hjcb0m.xml' applied
 installer: Installing at base path /
 installer: The install was successful.
 ?  mactex was successfully installed!

You have now installed TeX.
So far, the following have been installed

• TeX Live-2018
• GUI Applications
  • BibDesk
  • LaTeXiT
  • TeX Live Utility
  • TeXShop

TeX Live updates.

Update the TeX Live installed with the tlmgr command.
In the terminal where the brew command was executed, the tlmgr command is not passed through because the environment variables have not been updated. Open a new terminal and the environment variables will be set, so run the following commands in the new terminal.

$ sudo tlmgr update --self --all

This also takes a lot of time… Take your time and wait.

Default paper size settings

Do the default settings for paper size. Here it is set to A4.

$ sudo tlmgr paper a4

The installation and configuration of TeX is now complete. Although it takes some time, it is very easy and very helpful. I was so thankful and grateful when I was a student that I had to say “hooray” to set up the TeX environment…

Generating PDFs from Sphinx

Once TeX has been set up, PDFs can be generated from Sphinx.
Run the following command in the Sphinx directory.

$ make latexpdf

If there are no problems, a latex folder is created at the build destination, and TeX-related files and PDF files are generated.