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.
The Makefile (in the top-level doc directory) automates the generation of the documents. To make the HTML documents:
For PDF documentation do:
The built documentation is then placed in a build/html or build/latex subdirectories.
For more options, type:
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:
to upload the docs to sourceforge.
The Sphinx website also has an excellent sphinx rest primer.
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.