# 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.

## 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::

  - reST primer

  - reST quick reference

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.