Fork me on GitHub

Sunday, May 1, 2011

Build API documentation using Sphinx

According to its website, Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

Install Sphinx
To install Sphinx in your Unix system use your distribution default installation mechanism or run the next command as root user.
# easy_install -U sphinx
Setting up documentation sources
To document a project using Sphinx we need to create a file which contains configuration options to build the documentation. We can create it automatically running sphinx-quickstart.
$ mkdir docs
$ cd docs
$ sphinx-quickstart
The sphinx-quickstart command asks you some questions about configuration, be sure to say yes to the autodoc extension.

Document your project
Now you have a and index.rst files in your docs directory. You can leave both files unchanged and start documenting your project API. For example, document the Cormoran cache module using autodoc:
$ vim cache.rst
And now run sphinx-build as follow to create html documentation:
$ cd ..
$ sphinx-build -b html docs _build
To explore the newly generated html documentation got to _build directory and open index.html.

To see a complete tutorial for documenting using Sphinx, go to its online tutorial.

The Cormoran API documentation is a great example of this tutorial.


  1. Nice short tutorial, but I would expand on this...
    Sphinx has useful directives and domain specific features
    that make writing documentation for your API really nice!

    You can see examples of this here:


  2. Hi James! Thank you for your comment ;)

    This is a very short tutorial, but for more specific features, the Sphinx oficial tutorial is the best.

    See you soon!