Documenting Python Code with Sphinx
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.
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.