How to create PDF from Sphinx documentation using LaTeX (Linux)

Includes information on the packages you need to install, creating a new sphinx project, and commands to build PDF documentation.

You can watch me do this on Linux Mint 20.2 in the video below.

Watch on YouTube

You should be able to do these steps on Ubuntu 20.04 LTS or distributions that are based on Ubuntu.

Outline of steps

  1. Install required packages
  2. Create a Sphinx project
  3. Build PDF documentation

If you have an existing Sphinx project, you can skip the second step.

Step 1 — Install required packages

Using Software Manager on Linux Mint or apt package manager (see commands below), you will need to install the following packages.

Python 3 venv module

Required to create a virtual environment for the Sphinx project. Install the python3-venv package.

LaTeX distribution and tools

latexmk
texlive-latex-recommended
texlive-latex-extra
texlive-xetex

If you’re only using the default fonts included with LaTeX, you don’t need to install texlive-xetex.

LaTeX fonts

fonts-freefont-otf
texlive-fonts-recommended
texlive-lang-greek
tex-gyre


To install these packages using apt on the command line, use:

sudo apt update

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

Once these packages are installed, you can proceed towards creating a new Sphinx project.

Step 2 — Create a Sphinx project

You will need to:

  1. Create a directory for the project
  2. Create a Python virtual environment
  3. Install Sphinx
  4. Run the sphinx-quickstart script

Create a directory for the project

Sphinx will create a number of files when creating a new project so, it is better to create a new directory.

Use mkdir to create the new directory and change into it using cd:

mkdir sphinx-pdf-demo
cd sphinx-pdf-demo

Create a Python virtual environment

You will install Sphinx will in this virtual environment.

Although you can install Sphinx from Linux package repositories (python3-sphinx package on Mint or Ubuntu or Debian), there are some advantages in creating a virtual environment. For example, you can:

  1. Use the latest version of Sphinx from PyPI
  2. Install additional Sphinx extensions and themes
  3. Install Python packages that are not available in Linux system repositories

If you have Sphinx installed already, skip to the “Run the sphinx-quickstart script” step.

To create a virtual environment, run the command:

python3 -m venv venv

Here -m is used to specify the module we would like to use — venv in this case. The final venv is the directory name, where the virtual environment will be created.

Activate the virtual environment using:

source venv/bin/activate

A (venv) should appear at the beginnning of the command prompt, indicating that the virtual environment is now active.

Before proceeding to install Sphinx, update the Python build tools — pip, setuptools and wheel.

To install (or update) Python build tools, use the command:

pip install -U pip setuptools wheel

Install Sphinx

To install Sphinx using pip, use the command:

pip install Sphinx

With Sphinx installed, you can proceed towards creating a new Sphinx project by running the included quickstart script.

Run the sphinx-quickstart script

While still in the sphinx-pdf-demo directory and with the virtual environment still active, run the command:

sphinx-quickstart

Answer the prompts. Here is a sample session:

Welcome to the Sphinx 4.3.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: Sphinx PDF Demo
> Author name(s): Vimalkumar Velayudhan
> Project release []: 0.1

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:

Creating file /home/vimal/sphinx-pdf-demo/source/conf.py.
Creating file /home/vimal/sphinx-pdf-demo/source/index.rst.
Creating file /home/vimal/sphinx-pdf-demo/Makefile.
Creating file /home/vimal/sphinx-pdf-demo/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /home/vimal/sphinx-pdf-demo/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

The Sphinx project has now been created. To preview, the quickest way is to build the HTML version of the documentation.

To do that, use the command:

make html

Then, from the build/html directory, open index.html in a browser. This will display the main page of the documentation.

Build PDF documentation

To build the PDF version of the documentation, use the command:

make latexpdf

Once complete, open sphinxpdfdemo.pdf from the build/latex directory.

This PDF will not have any content. Let’s add some.

Copy the contents below to a new text file:

Sample chapter
==============
This is a paragraph.


A section
---------
A paragraph in section.

.. note::

   This is a note.

A subsection
............

.. attention::

   Something that requires attention.

Adding footnotes
----------------
Some text that requires a footnote [1]_.

To see how to add content of this footnote, scroll down to
the bottom of this page.

Including abbreviations
-----------------------
Use the ``:abbr:`` directive, for example:
:abbr:`LIFO (last-in, first-out)`

Inserting links
---------------
To other documents in this book, use ``:doc:`` with the
path to the file. For example, :doc:`index`.

You can insert link to external websites
`inline <https://vimalkvn.com>`_ or
define them separately_.
See the links section at the end of this page.

Code samples
------------

.. code-block:: python

    # import os
    # import sys
    # sys.path.insert(0, os.path.abspath('.'))
    from string import Template

---

.. rubric:: Footnotes

.. [1] Text of the first footnote.
   More text here.


.. Links

.. _separately: https://vimalkvn.com/leanbook

Save the file as sample-chapter.rst in the source directory.

Add sample chapter to table of contents in the index page i.e., index.rst.

.. toctree::
   :maxdepth: 2
   :caption: Contents

   sample-chapter

Re-build PDF documentation:

make latexpdf

The PDF file should now have the sample chapter included.

Reference

Sphinx documentation