Documenting Your Project With reStructuredText¶
Read time: 29 minutes (7285 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. That support tool is named pip
. This
program will install Python libraries published by developers all over the
world by running a simple command on your command-line:
$ pip install packagename
Pip
will download the named package and install it in your Python
installation so it is ready to use. If that package needs anything else, pip
will install that as well. In the end, you should be ready to use the new tool.
Let’s get ready to go:
Windows Setup¶
If you installed Python3 using the standard Python installer, you should have
the needed tools. Pip
is not installed in the same folder as Python
itself. That means we need to edit the system PATH variable, and add one more
folder.
On my PC, I installed Python 3.7 under C:\tools\Python37
. Pip
is
located under C\tools\Python37\Scripts
. When I added that to the system
PATH (see the notes in the appendix on how to do that). pip
was ready to
run:
$ pip --version
pip 10.0.1 from c:\tools\Python37\lib\site-packages\pip (python 37)
That tells me I am ready to go.
Mac¶
On Mac systems, you should be using HomeBrew to load things. Here is how I set up my Mac for Python development:
$ brew install python
$ python --version
$ pip3 --version
Warning
On Mac systems, if you run pip
, you are using Python 2.7. We need to
run pip3 to get the correct versions of our libraries. My examples will
show ``pip3
as the command.
Linux¶
I use Ubuntu Linus. Run these commands to get things set up:
$ sudo apt-get install python3
$ sudo apt-get install python3-pip
Documentation Setup¶
The first thing you need to do is set up a folder for your documentation. The
usual home for this is a docs
folder at the root of your project folder.
However, we will be publishing our documentation on GitHub, so we want to
reserve docs
for actual web pages. On my projects, I set up a folder named
rst
where I place all of my documentation files. Sphinx will process those
files and build the web pages i need in the docs
folder. :
$ cd <project root>
$ mkdir docs
$ mkdir rst
Installing Sphinx¶
With these folders in place, it is time to install Sphinx
$ pip3 install sphinx
$ pip3 install sphinx-rtd-theme
That last line installs a theme I like to use on my documentation. We will configure our project to use this theme in this note.
Initializing the Documentation¶
Sphinx comes with a tool for setting up a documenting project. We will use that tool for the next step:
$ cd rst
$ sphinx-quickstart
That 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).
Be sure to say “yes” when it asks if you want a nojekyll
file. We will need
that if we want to see our web pages on GitHub.
Note
On PC systems, create a file named build.bat
in the rst
folder. Place this line in that file:
sphinx-build -b html -d _build/doctrees . ../docs
Save this file when done.
Running Sphinx¶
To test your setup, or to build your documentation, open a command line in your
rst
folder, and do this:
$ build
When this command completes, you fill find web pages in the docs
folder we
set up earlier. Using Windows Explorer, navigate to that folder and
double-click on the index.html
file. You should see your web pages in
your browser.
Adding a Theme¶
The default theme is a bit ugly for my tastes. In the rst
folder, there is
a file named conf.py
. This file has a lot of stuff in it we really do not
need. I usually strip away most of the “fluff” and use something simple, like
this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | # -*- coding: utf-8 -*-
import os
import sys
import sphinx_rtd_theme
sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'SphinxDemo'
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'
|
Look this over, and change the lines that obviously are about you and your project. Leave everything else alone.
Build your docs again, and open up index.html
. You should see something a
bit nicer.
If you get to this point, you are ready to document. There is still a bit of work to do, though
Publishing on GitHub¶
Of course, your project is on GitHub and you are using Git to manage things. Here is what you need to do next:
- Reference
Repository Setup¶
Before you can get web pages published on GitHub make sure you have built your
documentation at lease once, and pushed your work (and web pages) to GitHub.
If the docs
folder does not exist, the following steps will not work.
Once you are ready, press on:
Open your project repository in GitHub.
Select
settings
Scroll down until you see the GitHub Pages area.
- Enable GitHub Pages for this project, then select
Master Branch/docs folder
as the source for your site.
Place any HTML file in that folder. (we did that by running Sphinx)
Navigate to https://ghuser.github.io/project-name to see your site
Note
Your website for class projects will appear at a URL that looks something like thi:
This website is available for free for any repository you set up on GitHub. I highly recommend learning how to do this, then building nice documentation for every project you create.
Warning
Public project, of course. School work should be kept private!
Learning reStructuredText¶
The next thing you need to do is to explore reStructuredText and get a feel for how you set up your documentation.
All of my lecture notes are written in reStructuredText markup, so you can use the :show source” link to see what I wrote Much of what you see is a bit advanced, because I have extended Sphinx with some additional “plugins” that let is do cool things. For you, just starting up< use one of the online tutorials on SPhinx to get started.
Here are a couple of useful links: