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
|
.. _documentation_faq:
===================
Documentation FAQ
===================
.. _installing_graphviz_on_OSX:
Installing graphviz on OSX
--------------------------
The easiest way I found to do this was using MacPorts_, all other
methods caused python exceptions when attempting to write out the pngs
in the inheritance_diagram.py functions. Just do::
sudo port install graphviz
And make sure your macports directory (``/opt/local/bin``) is in your PATH.
Error writing output on OSX
---------------------------
If you are getting an error during the **writing output...** phase of
the documentation build you may have a problem with your graphviz_
install. The error may look something like::
**writing output...** about api/generated/gen
api/generated/nipy
api/generated/nipy.algorithms.fwhm Format: "png" not
recognized. Use one of: canon cmap cmapx cmapx_np dia dot eps fig
hpgl imap imap_np ismap mif mp pcl pic plain plain-ext ps ps2 svg
svgz tk vml vmlz vtx xdot
...
Exception occurred:
File "/Users/cburns/src/nipy-repo/trunk-dev/doc/sphinxext/
inheritance_diagram.py", line 238, in generate_dot
(name, self._format_node_options(this_node_options)))
IOError: [Errno 32] Broken pipe
Try installing graphviz using MacPorts_. See the
:ref:`installing_graphviz_on_OSX` for instructions.
Sphinx and reST gotchas
-----------------------
Docstrings
^^^^^^^^^^
Sphinx_ and reST_ can be very picky about whitespace. For example, in
the docstring below the *Parameters* section will render correctly,
where the *Returns* section will not. By correctly I mean Sphinx will
insert a link to the CoordinateSystem class in place of the
cross-reference *:class:`CoordinateSystem`*. The *Returns* section
will be rendered exactly as shown below with the *:class:* identifier
and the backticks around CoordinateSystem. This section fails because
of the missing whitespace between ``product_coord_system`` and the
colon ``:``.
::
Parameters
----------
coord_systems : sequence of :class:`CoordinateSystem`
Returns
-------
product_coord_system: :class:`CoordinateSystem`
.. include:: ../links_names.txt
|
