Documenting Python Code with Sphinx

2011-07-28
~
3 min read

One of the essential tasks in software development is documenting your code. With no documentation, hardly anyone will be able to understand your code and therefore contribute to your project. Sometimes you might find even yourself looking at your own code wandering, “What the hell is this supposed to mean?” Well, that’s where documentation comes in!

Good idea is to include documentation right into the source files. First of all, it helps coders read the source, because if they don’t get something, the documentation is right there! It’s much easier to maintain correct documentation. If you change something, you also change it 10 lines above in the documentation string. There are lots of utilities for analyzing source files and generating documentation from them. JavaDoc for Java, doxygen for C++ and Sphinx for Python.

I assume you know the awesome-looking Python docs, right? Well, that documentation is generated by Sphinx! In this post I’ll try to explain how to get sphinx and most importantly how to get that sweet-looking documentation out of it :-).

Installation

Sphinx is distributed as a python module, so you can use easy_install to get it. Install sphinx and all the dependencies by writing:

$ sudo easy_install sphinx

Easy install is a part of setuptools. So if this doesn’t run anything you probably need to install them. Look for package python-setuptools in your distribution’s repositary.

Setting up the doc/ folder

Documentation is usualy placed in a separate folder in your project directory. It’s really up to you, but I recomend using doc/ folder. Then you need to setup basic files for sphinx in that particular folder (sphinx calls it a source directory). This can be done by sphinx-quickstart command that will guide you through the whole setup process. The important thing here is to answer yes to the question of enabling autodoc extension. This extension then collect the documentation from your code.

$ mkdir doc
$ cd doc/
$ sphinx-quickstart

Writing documentation

The above mentioned sequence of commands should create a basic directory structure of your sphinx documentation. Somewhere in that structure (it depends on how did you answer to the questions of sphinx-quickstart ) will be an index file of the whole docs. By default it will be called index.rst . Content of this file is in reStructured text. It’s a syntax for formating plain text documents. It’s not very hard to learn. Using either rst quick reference, sphinx guide or my personal favorite way – copy-pasting from python docs.

On every html page generated by sphinx is a link to the source rst file it were generated from. And so it is in the python docs. The link is at the bottom of the menu right above the search box. You see, the documentation of python is not only quite large, but also really well formed. So by looking at that you’ll be soon able to write some pretty good docs yourself.

Sphinx doc example
Sphinx documentation example.

If you decide to crate a new page, you can simply add a file to the doc/ directory and sphinx will find it and include it into the documentation.

Documentation from docs string isn’t included automatically like in doxygen. You need to specify where to include what. In-depth explanation on how to do that is here.

Conclusion

Well, this was my very brief experience with sphinx. It’s a great tool for creating documentation for your python projects. Hopefully, I’ll get back to it at some point in the future and expand this article.

Sources