Generate PDF in a Sphinx Project Using LaTeX on Linux
In this tutorial, I will walk you through the process of creating PDF output in a Sphinx documentation project using the LaTeX builder on Linux. I will install required packages, create a Sphinx project, add a sample chapter, and then build a PDF of the entire project.
Note: I followed this procedure on Linux Mint 20.2, but these steps should also work on Ubuntu 20.04 LTS or its derivatives.
Step 1: Install required packages
Using Software Manager or apt, install the following packages.
python3-venvlatexmktexlive-latex-recommendedtexlive-latex-extratexlive-xetex(see note below)fonts-freefont-otftexlive-fonts-recommendedtexlive-lang-greektex-gyre
If you are using apt, update the package cache:
sudo apt update
Then install packages:
sudo apt install fonts-freefont-otf latexmk python3-venv \
texlive-fonts-recommended texlive-latex-recommended \
texlive-latex-extra texlive-lang-greek \
tex-gyre texlive-xetex
Step 2: Create Sphinx project
Sphinx will create a number of files when creating a new project so it is better to create a new directory:
mkdir sphinx-pdf-demo
Change into the new directory and create a virtual environment:
cd sphinx-pdf-demo
python3 -m venv venv
Here -m is used to specify the module we would like to use — venv in this case. The second venv in the example above is the name of the directory where the virtual environment will be created.
Activate the virtual environment:
source venv/bin/activate
A (venv) label should now appear at the beginning of the command prompt, indicating that the virtual environment is now active.
You can install Sphinx from Linux package repositories, but there are some advantages in creating and using a virtual environment, for example, you can use the latest version of Sphinx, install additional Python packages or Sphinx extensions, or use Sphinx themes that are not yet available in the Linux package repositories.
Before installing Sphinx, install the necessary Python build tools. This will ensure further packages will build and install without problems.
pip install -U pip setuptools wheel
Now install Sphinx:
pip install Sphinx
To create a new Sphinx project, run the sphinx-quickstart script that is included with Sphinx.
While still in the sphinx-pdf-demo directory and with the virtual environment still active, type:
sphinx-quickstart
Answer the prompts.
Here is a sample terminal session:
The Sphinx project is now created. To preview it, the quickest way is to build the HTML version. To do that, type:
make html
Using file manager, navigate to the build/html directory of the project and open index.html in a browser.
This will display the main page.
Step 3: Build PDF output
To build the PDF version, type:
make latexpdf
Once the build process is complete, open sphinxpdfdemo.pdf in the build/latex directory.
This file will not have any content. Let's add some!
Save the following file as sample-chapter.rst in the source directory.
Add sample chapter to table of contents in index.rst:
.. toctree::
:maxdepth: 2
:caption: Contents
sample-chapter
Save the file.
Now, rebuild PDF:
make latexpdf
The resulting PDF file will include the sample chapter.
