[AstroPy] Documentation Guidelines

Mark Sienkiewicz sienkiew at stsci.edu
Tue Jul 12 16:23:29 EDT 2011

>> If that is good enough, then we don't need to consider more complicated
>> markup in the docstring.
> Do you have any sectioning in the pywcs format?  Some of the astropy
> classes will no doubt be rather complex, and hence they will require
> things like lists and "seealso" sections and references... I'm
> concerned that if the format doesn't have any syntactic hints (that
> sphinx will process to organize the doc), it will be difficult to read
> for more elaborate docstrings.

Well, what I know is pywcs is maintained here, and we are supposed to be 
moving to using numpy docstring format.  Obviously, I picked out the 
wrong example, but it doesn't matter now that you have put examples up 
on your web page.

We should just use the numpy format because it is so much easier to read 
than the sphinx format.  The coding standards it should include a link 
to what the format is.

b.t.w.  If a package showed up with docstrings that look like the pywcs 
example, I wouldn't necessarily turn it away.  (Rejecting sub-standard 
product is what the standards are about, after all.)  If a package 
showed up with docstrings epydoc format, I might ask for the docstrings 
to be revised before accepting it into astropy.

More information about the AstroPy mailing list