Getting started with Sphinx

Create a documentation folder

Create a new folder for storing all files related to documentation by running the following command:

mkdir docs

sphinx-quickstart

Sphinx comes with a handy ‘quickstart’ feature, which is a script that generates default source and build directories, along with a configuration file conf.py for easily compiling the Sphinx documentation for your project.

To use this feature, navigate to inside the newly created documentation folder:

cd docs

Now run the Sphinx quickstart command:

sphinx-quickstart

A list of options for customising some of the sphinx-quickstart features should now pop up on the screen. The first of these options asks whether seperate source and build directories should be created for the documentation. For dcmri’s documentation ‘yes’ was chosen by responding y + Enter:

Now enter a name for your project and author(s) and a version number for the project release:

And finally, choose a language for the project language (simply hitting the Enter button chooses the default option displayed in square brackets e.g., English in this case [en]):

Sphinx should now start compiling the project. Once completed the project documentation folder docs should look like this:

Makefile (linux) and make.bat (Windows) are shell and batch scripts, respectively, created by Sphinx that make life easier when it comes to actually building the html pages. These scripts build the html pages, and are executed in conjunction with the command make. More details below, in (Build a basic html).

The build directory is for storing all of the html pages built with Sphinx, together forming the documentation for the project.

The source directory contains all content that will be used to actually build the html pages.

Build a basic html

To get a feel for how Sphinx works and what the project documentation could look like, run the following command to build a basic html:

make html

This should create a basic and uncustomised html page which looks like like this:

To check this, open the index.html which was created in the docs/build/ directory:

The following sections demonstrate how to populate this plain html with documentation for the project.