NIPY logo

Table Of Contents

Previous topic

Development Guidelines

Next topic

Documentation FAQ

Community Site

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.

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 build the root part of the website using sphinx:

git co http://github.com/nipy/nipyco.git
cd nipyco
make html

then open _build/html/index.html in your browser to preview the docs.

I (Matthew) then use:

make upload-html-matthewbrett

to upload the docs to sourceforge.

Syntax

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

Style

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.