Compile to HTML: Set Up Sphinx

Installing Sphinx

To use Sphinx, we first need to install it using the following command in the terminal.

export LC_ALL=C.UTF-8 && export LANG=C.UTF-8
pipenv install --dev sphinx

Note: Here, it’s already been installed.

Sphinx comes with the tools sphinx-quickstart, sphinx-autogen, sphinx-build, and sphinx-apidoc.

Let’s explore each, beginning with sphinx-quickstart. We’ll run it from the root of our software project. Here, we run it in the directory with flask examples that have the code used in the Flask chapter. To get to this directory, use the following command in the terminal.

cd frap-api

Creating the project directory

To start, the following command creates the Sphinx directory for the project, calls the project “Flask Examples” and lists the author as “Erik M. Ferragut”. It also activates the autodoc plug-in.

sphinx-quickstart --project "Flask Examples" --author "Erik M. Ferragut" --ext-autodoc --sep docs

As this runs, it provides many prompts. We’ll select the default, given in square brackets, by hitting the enter key (or “Return”) in each case. Other extensions we may want to play with include coverage, doctest, and todo. If we ever use equations in our documentation, we can also use the mathjax extension. When it’s done, it will create a new directory called docs containing several files: