[AstroPy] Documentation Guidelines

[Prasanth]

Hello,

Seeing numpy docstrings in action, I think that would be preferable to the
Sphinx-suggested format. numpydoc can be pip installed, so installing it
won't be a problem. And, like epydoc, we can generate inheritance diagrams
using the sphinx.ext.inheritance_diagram extension.

Prasanth


On Wed, Jul 13, 2011 at 1:53 AM, Mark Sienkiewicz <sienkiew at stsci.edu>wrote:

>
> >> 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.
>
>
> _______________________________________________
> AstroPy mailing list
> AstroPy at scipy.org
> http://mail.scipy.org/mailman/listinfo/astropy
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/astropy/attachments/20110713/53fc4c34/attachment.html>