Docstring format in PySPH

[Pankaj Pandey]

Recently while trying to enable sphinx autodoc extension for pysph i came across this sphinx convention for docstrings ( http://sphinx.pocoo.org/domains.html#info-field-lists ) which is basically:
    :param [type] name: <doc>

About halfway through the conversion of existing docs i came across a different format used by numpy and friends ( https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#id7 ) which is:
Parameters
----------
  x : type
    Description of parameter `x`.

Now i wish to open for discussion which format to use. Our choices are:
1. Use the numpy format (most docstrings are already in that format).
It will need us to include the numpy docstring parser extension for sphinx (https://github.com/numpy/numpy/blob/master/doc/sphinxext/numpydoc.py - need to check license) in PySPH for the docstrings to be useful (else it gives parser errors in sphinx: invalid in rest)
2. Switch over to using the default sphinx format. I've attempted to convert a few files before i came across the numpy format

[Pankaj Pandey]

Well i just saw Mayavi also already includes numpydoc.py sphinx extension in its sources so we should also probably go with it. It also seems well documented and much widely used. If there's consensus i'll put the numpydoc.py into our doc sources too.

[Prabhu Ramachandran]

Yes, please do so. Go ahead and use the numpy style. I don't think we
have any traits code but there is an extension for traits also that
ships with Mayavi. For now I think the numpydoc.py will do fine.

Thanks.

cheers,

--
Prabhu Ramachandran http://www.aero.iitb.ac.in/~prabhu