An Introduction To Sphinx

What is Sphinx? Well, in a nutshell, Sphinx is a Python documentation generator, but in reality, it is so much more. Sphinx has the rather impressive capability of converting reStructuredText and Markdown documents into HTML files, PDF’s and much more.

This means with Sphinx, you have the capability to create entire static sites out of Markdown documents, which is pretty nifty! Sphinx gives you the capability to create custom themes whilst also providing an abundance of prebuilt options and configurations.

How do I get started Sphinx, well a good place to start is the installation guide and getting started guide on the official site. You will need to ensure you have Python installed along with a package manager such as pip or brew.

The first thing I did to get to grips with Sphinx was creating a quick start project using the following command.

sphinx-quickstart

This will give you a template to work from, it generates all relevant files and provides a default theme.

The File Structure

A useful place to start when learning Sphinx is to acquire an understanding of the file structure and what roles each file has.

The config.py file

This file is where you can configure how Sphinx reads your sources and builds your documentation. We can do a number of clever things here such as specify theming options such as favicons, add project information, specify our index amongst an abundance of other things. You can see a list of the many options available here.

index.rst

index.rst (also known as the master document) is our welcome/root home page, the primary purpose of this file is to manage the root of our toctree (our table of contents tree). Take a look at the example below taken from the Sphinx website.

.. toctree::
:maxdepth: 2

intro
strings
datatypes
numeric

This example inserts a toctree at the current location, including a number of sub-TOC trees (intro, strings, datatypes, numeric). maxdepth sets a maximum depth of two, meaning only one subheading will be included for each sub-TOC.

Makefile/make.bat

So what the heck are these two files? Both files a for the purpose of configuring sphinx-build’s behavior.

make.bat specifically is a Batch (.bat) file, so it only contains sequences of commands and statements specific to Windows, whether or not you’ll need to use it will differ depending on your environment. If you are on a Windows machine it is here you’ll need to look if you wish to configure options such as build paths and environment variables.

The Makefile has its own special rules to indicate dependencies and is likewise used to customize sphinx-build’s behavior. To find out more on how to implement these customizations take a look at this part of the official documentation.

_build > Doctrees

The build directory contains a few things

> doctrees

Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as “doctree pickles”

This directory by default will have an index.doctree and environment.pickle.

_build > html

_sources

The sources directory by default is where our restructured text files will live, it is here sphinx-build looks when running the make methods.

_build/_static

The static file is where we’ll see the true magic sphinx, this file will contain all the generated javascript, HTML and CSS created when running commands such as..

make html 

_static

The static folder is where we keep things such as custom favicons, logos, and CSS. An overview of how to implement this can be found here.

_templates

It is in this file we can override the project’s default template to customize the output of our documentation, you can see an example of this in action here.

When building Sphinx will look for templates in the folders of templates_path first, and if it can’t find the template it’s looking for there, it falls back to the selected theme’s default template.

Hi, I’m Steven, most call me Steve! I’m a programmer, musician, and artist. This blog contains various tutorials and posts related to software development.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store