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