How to write documentation

Nipy uses the Sphinx documentation generating tool. Sphinx translates reST formatted documents into html and pdf documents. All our documents and docstrings are in reST format, this allows us to have both human-readable docstrings when viewed in ipython, and web and print quality documentation.

Getting build dependencies

Building the documentation

You need to have Sphinx (version 0.6.2 or above) and graphviz (version 2.20 or greater).

The Makefile (in the top-level doc directory) automates the generation of the documents. To make the HTML documents:

make html

For PDF documentation do:

make pdf

The built documentation is then placed in a build/html or build/latex subdirectories.

For more options, type:

make help

Viewing the documentation

We also build our website using sphinx. All of the documentation in the docs directory is included on the website. There are a few files that are website only and these are placed in the www directory. The easiest way to view the documentation while editing is to build the website and open the local build in your browser:

make web

Then open www/build/html/index.html in your browser.


Please have a look at our Sphinx Cheat Sheet for examples on using Sphinx and reST in our documentation.

The Sphinx website also has an excellent sphinx rest primer.

Additional reST references::

Consider using emacs for editing rst files - see ReST mode


Nipy has adopted the numpy documentation standards. The numpy coding style guideline is the main reference for how to format the documentation in your code. It’s also useful to look at the source reST file that generates the coding style guideline.

Numpy has a detailed example for writing docstrings.

Documentation Problems

See our Documentation FAQ if you are having problems building or writing the documentation.