Sphinx Documentation Generator – Tutorial 2

Sphinx – first project output

A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners.


In this second part of my Sphinx Tutorial we use the ‘quickstart’ script provided with Sphinx to quickly produce a basic set of documentation source files.

Our First Sphinx Project

Sphinx has a great way to get you started and that’s the ‘quickstart’ script (you’ll find sphinx-quickstart-script.py in the Scripts directory of your Python installation). Quickstart walks you through a series of questions to produce a basic set of the files you’ll need to produce your documentation.

Quickstart is pretty easy to use and even more so when your aim is to produce something very basic (which is the aim of this tutorial).

We’ll just step through the more important bits here :

Specify where you want the Documentation to be created

Sphinx is going to create some files and a few directories so choose where you want those to be created :
Enter the root path for documentation.
> Root path for the documentation [.]: C:\data\src\Sphinx\Test1

Specify a name for the Documentation:

What ever name you choose will appear in various places in the documentation so choose something you’re happy with

The project name will occur in several places in the built documentation.
> Project name: Sphinx Tutorial
> Author name(s): Richard Shea

Specify a version for the Documentation:

Similarly you’ll get the version number appearing in various parts of the output documenation

> Project version: 1.0.0

Specify if you want any clever stuff:

Sphinx is able to do all sorts of clever stuff apart from interpreting your RST files into beautiful output. We don’t want any of that for the first part of the tutorial so say ‘no’ to all of this.

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:

Make it easy on yourself (at least to start with)

It’s perfectly reasonable to use build the Sphinx output by providing your own command line options but to get started with it’s helpful to allow Sphinx to help a little so say ‘yes’ to a .BAT or a makefile (depending on what’s your choice of poison).

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:

The results of quickstart

So after all that what have we got ? Well we specified C:\data\src\Sphinx\Test1 as the output path and if we look in there we find we’ve got a build and a source directory (as well as the Makefile and make.bat we asked for). What we’re interested in to start with is source\index.rst.

Open it up in a text editor and you’ll see it looks like this :
.. Sphinx Tutorial documentation master file, created by
sphinx-quickstart on Sun Nov 1 18:08:19 2009.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to Sphinx Tutorial's documentation!


.. toctree::
:maxdepth: 2

Indices and tables

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Next Steps

In the next part of this series, Sphinx – Absolute Beginners – Part 3, we’ll see how to make this file into either HTML or PDF output. In later parts of the series we’ll see how to use your existing Python code comments to produce automated documentation of your Python code.

Leave a Reply

Your email address will not be published. Required fields are marked *