[AstroPy] Documentation Guidelines
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