Documenting Your Project With reStructuredText

Read time: 19 minutes (4777 words)

You absolutely should be writing documentation at the same time you write code. No, I do not mean add comments to your code! I mean write a separate document that explains your code to some poor soul who will inherit your creation and have to “maintain” it. You need to establish a habit of working on your documentation, and treat that as something as important as the code itself!

Good Documentation

What makes for good documentation?

For one thing, it is designed to convey information to the reader. But who is that reader? Perhaps it is you a week from now, when you have forgotten why you did what you did. Most certainly, it is another developer who inherits your code a year from now, when you are not around to help out. Maybe you are working on another project, maybe you have left the company. Who knows?

Donald Knuth, one of the most respected computer scientists this country has produced, thought this was so important, he proposed a new way of programming he called Literate Programming.

In his system, you wrote the source code for a book, describing the code you were developing. That code was processed using another great tool developed by Knuth, the TeX typesetting system, and generated something a published could use to print a real book (or, today, a nice PDF). Where is the code you need to compile? It is buried in the documentation source, and extracted by a tool designed to generate the code file the compiler could process. Knuth was concerned that documentation and code might wander in different directions, so he made is hard for humans to read the generated code. The compiler could care less, so Knuth hoped that developers would stay focused on writing the “literate” documentation instead.

Knuth’s system never really took off, but it became part of the programming landscape, and still has many proponents (including me)!

Writing Documentation

To get you started in writing this documentation, I am going to have you use a very popular system for processing your documentation into something easy to read. Shoot, you are reading the product of that system right now. I have been using this tool for my lecture notes ever since it hit the planet in 2008!

The tool we will use is Sphinx, a Python tool that has a huge following now. Although it was designed to support documenting the Python project, itself, developers are using it for all kinds of projects, not just Python projects.

Prerequisites

In order to use Sphinx, you need to have Python installed, and a support tool used to install Python libraries:

PC Setup

On a PC, install the latest release of Python from the project website.

Mac Setup

On a Mac, using HomeBrew, installing Python is as easy as this:

$ brew install python3

Of course, you can use the installer, also available on the project website.

Linux Setup

On a Ubuntu Linux system, the needed tools are installed like so:

$ sudo apt-get install python3
$ sudo apt-get install python3-pip

Verify Tools

Check your setup on any system by running these commands from the command line:

* python --version
  Python 3.6.5
$ pip --version
pip 9.0.3

Note

I needed to update pip on my system, which I did by doing this:

$ pip install --upgrade pip

Documentation Setup

The first thing you need to do is set up a folder for your documentation. The usual home I set up for this is a rst folder at the root of your project folder. The web pages we produce will be created in another folder named docs. By doing this, you can get a website for free for your project from GitHub (see below).

$ cd <project root>
$ mkdir rst
$ mkdir docs

Installing Tools

With pip installed, it is common to create a file named requirements.txt where you list the libraries you need. For my Python projects, my requirements.txt file looks like this:

requirements.txt

sphinx
sphinx-rtd-theme

With this file in place, run this command to install everything needed:

$ pip install -r requirements.txt

Note

You can install things manually by doing this instead:

$ pip install sphinx
$ pip install sphinx-rtd-theme

The Sphinx tool is just a Python application. The sphinx-rtd-theme includes code needed to style your website. I an currently using the theme used on Read The Docs, a popular website where developers put their project documentation.

We will not use that system. Instead, we will publish our documentation on GitHub.

Initialize Documentation

Sphinx uses a simple python configuration file to manage its operation. You can get a baasic starter setup easily by doing this:

$ cd rst
$ sphinx-quickstart

That above command will set up the SPhinx project. You will be asked a bunch of questions, most of which you can just leave as the default answer (except for your name and the project name).

Add the Theme

Before we can use the RTD theme, we need to modify the conf.py file a bit. Here is a stripped down version of the file I actually use for most projects:

rst/conf.py

# -*- coding: utf-8 -*-

import os
import sys
import sphinx_rtd_theme

sys.path.insert(0, os.path.abspath('.'))

# -- Project information -----------------------------------------------------

project = 'N5UJHnotes'
copyright = '2018, Roie R. Black'
author = 'Roie R. Black'

version = '3.0.1'
release = '3.0.1'
language = None
today_fmt = '%B %d, %Y'

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.githubpages',
]
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'

# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme'
html_theme_options = { }
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']
html_use_smartypants = True
html_show_sourcelink = True
html_show_sphinx = True
html_show_copyright = True
html_last_updated_fmt = '%b %d, %Y'

# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
    'papersize': 'letterpaper',
    'pointsize': '12pt',
    'figure_align': 'htbp',
}

latex_documents = [
        (master_doc, 'N5UJHnotes.tex', 'N5UJH: Ham Radio Notes',
     'Roie R. Black', 'manual'),
]

# -- Extension configuration -------------------------------------------------

Running Sphinx ==============

To test your setup, or to build your documentation, open a command line in your docs folder, and do this:

$ make html

You should find a new folder, docs/_build. In that folder you will have a html folder. Open up the index.html file you find there with your browser to see your nicely formatted documentation.

You can learn more about using Sphinx from the project website, or look around on GitHub for examples. My class notes are all done using this tool.