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