[AstroPy] Documentation Guidelines

[Brian Kloppenborg]

Tom and others,

On 07/12/2011 12:11 PM, Thomas Robitaille wrote:
> I've added this to the options discussed so far shown at
> https://github.com/astrofrog/astropy_doc_test
>
> Cheers,
> Tom

Thank you for making this display example.

I vastly prefer the Numpy/Scipy format.  The documentation is easy to 
read both in the source code and in the Sphinx output.  It also will be 
in line with the dominant math/science package in Python so it appears a 
clear first choice to me.

Commenting on the other two formats:
The "Sphinx suggested Format" does produce nicely condensed output, but 
the source code and docstrings are much more difficult to read.  Just to 
find the parameter names you have to visually parse

:param str file_name:

compared to

file_name : str

which, in my opinion, destroys the ease-of-lookup factor.

The PyWCS format is by far my least favorite as the ouput parameter 
names from Sphinx are not in bold.  Can this be changed?

Brian