Documentation FAQ

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 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`