1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
.. _howto_document:
============================
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 :ref:`sphinx_helpers` 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 <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_
- `reST quick reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
Consider using emacs for editing rst files - see :ref:`rst_emacs`
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
<http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_DOCUMENT.txt>`_ that
generates the coding style guideline.
Numpy has a `detailed example
<http://svn.scipy.org/svn/numpy/trunk/doc/EXAMPLE_DOCSTRING.txt>`_ for
writing docstrings.
.. _`numpy coding style guideline`:
http://scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
Documentation Problems
----------------------
See our :ref:`documentation_faq` if you are having problems building
or writing the documentation.
.. include:: ../../links_names.txt
|
