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 conf.py 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 conf.py 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.

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