Hello,<div><br></div><div>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.</div>
<div><br></div><div>Prasanth</div><div><br><br><div class="gmail_quote">On Wed, Jul 13, 2011 at 1:53 AM, Mark Sienkiewicz <span dir="ltr"><<a href="mailto:sienkiew@stsci.edu">sienkiew@stsci.edu</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im"><br>
>> If that is good enough, then we don't need to consider more complicated<br>
>> markup in the docstring.<br>
> Do you have any sectioning in the pywcs format?  Some of the astropy<br>
> classes will no doubt be rather complex, and hence they will require<br>
> things like lists and "seealso" sections and references... I'm<br>
> concerned that if the format doesn't have any syntactic hints (that<br>
> sphinx will process to organize the doc), it will be difficult to read<br>
> for more elaborate docstrings.<br>
<br>
</div>Well, what I know is pywcs is maintained here, and we are supposed to be<br>
moving to using numpy docstring format.  Obviously, I picked out the<br>
wrong example, but it doesn't matter now that you have put examples up<br>
on your web page.<br>
<br>
We should just use the numpy format because it is so much easier to read<br>
than the sphinx format.  The coding standards it should include a link<br>
to what the format is.<br>
<br>
b.t.w.  If a package showed up with docstrings that look like the pywcs<br>
example, I wouldn't necessarily turn it away.  (Rejecting sub-standard<br>
product is what the standards are about, after all.)  If a package<br>
showed up with docstrings epydoc format, I might ask for the docstrings<br>
to be revised before accepting it into astropy.<br>
<div><div></div><div class="h5"><br>
<br>
_______________________________________________<br>
AstroPy mailing list<br>
<a href="mailto:AstroPy@scipy.org">AstroPy@scipy.org</a><br>
<a href="http://mail.scipy.org/mailman/listinfo/astropy" target="_blank">http://mail.scipy.org/mailman/listinfo/astropy</a><br>
</div></div></blockquote></div><br></div>