Documentation with Sphinx
As you know, documentation is important for any software we write, for both users and developers. Writing documentation, however, is painful. We have to deal with the quirks of the word processor, text formatting, image placement, table of contents, etc.
Sphinx is a tool that helps you create documentation easily. It automates many of the annoying tasks in creating documentation, and lets you concentrate on the content. Their website quotes a user saying that it "makes programmers want to write documentation!" I wouldn't go that far, but it really frees you from the frustrations around writing documentation.
In this post, I'll go over installing and configuring Sphinx, writing your documentation, and finally building it as a PDF file. Much of the material is detailed in First Steps with Sphinx, but I've made some changes to the standard configuration.
Installation
I recommend that you use Cygwin as your command-line environment. You'll be able to install and run Sphinx quickly. In the Cygwin setup program, add the following packages: python, python-sphinx, make, texlive, latex-recommended, latex-extra, and fonts-recommended.
If you're not using Cygwin, follow the steps in Installing Sphinx. You'll also need to install LaTeX to generate your documentation as a PDF file (see Obtaining LaTeX).
Configuration
Using a command-line terminal, create a directory where you'd like to keep your documentation. Go into that directory and run sphinx-quickstart, which will ask you a few questions to help you set up your Sphinx configuration and build files. I recommend accepting the default values for most of the questions, except for the following cases:
Separate source and build directories? Answer yes to this question. I think that keeping the source and the build files in different directories is more organized.
Name prefix for templates and static dir. Use "." as the prefix. Since I'm using Cygwin, I'm used to using a "." for system and hidden files or directories.
Project name and Author name(s). There are no defaults for these, so you must enter the correct information here, such as "CoolScript" and "Carlos Anderson" (or the author could be the name of your institution).
Project version. This also does not have a default, so you must enter a value. For most scripts I use a version with four parts, but for the documentation I only use two. For example, if my script's version is 1.2.3.4, the documentation version would be 1.2. This is because I use the third and fourth version parts for bug fixes and builds, so typically there's no need to change the documentation for such changes.
pngmath: include math, rendered as PNG images. If you're going to include mathematical equations in your documentation, answer yes. I always answer yes, just in case.
Create Windows command file? If you're using Cygwin or a Linux/MacOSX terminal, answer no. If you're using the Windows terminal, answer yes.
Once finished, the quick start program will create a Makefile (or make.bat), the source directory, and the build directory. In the source directory, there are two files: conf.py and index.rst.
conf.py is the configuration file for your Sphinx project (see The build configuration file). You typically won't need to change the contents of this file, except for a few things. Whenever you update the documentation for a new release of your script, you'll want to change the "version."
In the section "Options for LaTeX output," uncomment the pointsize option and change it to 12pt. I find the slightly bigger font easier to read. Also, Sphinx adds some blank pages to the output that don't make sense for a digital documentation, so get rid of them by adding the following lines before the ending brace inside latex_elements:
'babel': '\\usepackage[english]{babel}',
'classoptions': ',openany,oneside'index.rst is the "master document" that tells Sphinx what your documentation should contain. There's extra stuff there that we don't need, so delete everything until you're left with just this:
Documentation Contents
======================
.. toctree::
:maxdepth: 2
introThe line "intro" says that there's a file called "intro.rst" that should be included in the documention (we'll create intro.rst soon). You can add more content by listing more files.
Write the Documentation
Each file you write corresponds to a chapter in the documentation. As an example, we'll write an Introduction chapter. Open a plan text editor and create a file named "intro.rst". Documentation files need to be written in reStructuredText (see reStructuredText Primer), which is a straightforward mark-up language. I won't go over all the reStructuredText commands, but here's a sample intro.rst:
Introduction
============
This is a word in *italics* and this is in **bold**.
The following is a list of numbered items or steps:
#. Do the first thing.
#. Do the second thing.
Here is a bulleted list:
* Thing 1
* Thing 2
Images
------
Here's how you include an image.
.. figure:: image.png
:width: 4in
Here is the figure caption.
.. _references:
References
----------
You can reference different parts of a document (even across files)
by labeling it, as done in this section, and reference it like this:
:ref:`references`.
Math
----
You can include complex math using LaTeX syntax:
.. math::
E(p) = \frac{1}{Y} \sum\limits_{j=1}^{m} y_j E(f_j)
which is rendered on its own line, but you can include
inline math like this: :math:`m = 10`.I've put this sample project on GitHub as CoolScriptDocumentation.
Build the Documentation
In the root directory of the documentation (not in the source directory), run "make latexpdf". If all goes well, a PDF will be produced in the build/latex directory. I've put my output PDF in the root directory of the GitHub repository linked above.
As you can see, Sphinx automatically creates a title page, a table of contents, and organizes your files into chapters. It also formats the documentation with a professional-looking style. Aside from the initial configuration, you only had to worry about the content.
One shortcoming with Sphinx is that it's not easy to change the style of the PDF documentation. There are resources online that can help you do these types of advanced configurations. Generally, though, I've been happy with the default style.
I recommend that you make this PDF easily available to anyone who will be using your script. For example, you could create a Help button or menu item that automatically opens the PDF when clicked.
Σχόλια