[SciPy-dev] [SciPy-user] Docstring standards for NumPy and SciPy

David Huard david.huard at gmail.com
Tue Jan 16 19:29:08 CST 2007


2007/1/16, Travis Oliphant <oliphant at ee.byu.edu>:
>
> In summary, my biggest issues with just straight restructured Text are
>
> 1) back-ticks in parameter lists.
> 2) the way math is included
> 3) doesn't understand Moin Moin tables
> 4) doesn't seem to have special processing for standard section headers
> (I may be wrong about this as I'm not an reST expert.
>
> I also don't really like the way bold, italics, and courier are
> handled.  My favorite is now *bold* /italics/ and  `fixed-width`.
>
> I like the {{{ code }}} for code blocks that Moin Moin uses, but that's
> not a big deal to me.  I can live with the :: that restructured-Text uses.
>
> It seems like we are going to have to customize (hack) epydoc to do what
> we want anyway.  Why then can we not "tweak" reST a little-bit too.
>
> -Travis
>

I understand Travis's reluctance to introduce a markup that doesn't look as
good as it could, but I'm bothered by the precedent it creates. I imagine
that in a couple of years from now, there will be a bunch of graphical IDEs
processing reST markup in the docstrings and generating a nice output. If we
go along with the SciPy markup, I'm worried user will be disapointed to see
that their favorite IDE cannot process SciPy and NumPy docstrings correctly.

Now that we've contacted epydoc's developper, maybe its time we discussed
the issue with the docutils folks, and see what their take on this is. If
they are willing to accept patches implementing solutions to some of the
issues Travis mentionned, the SciPy docstring effort would serve other
projects as well, be maintained over time and remain compatible with third
party software. To my knowledge, there is no convention yet regarding reST
docstrings, so let's use this opportunity to voice our needs.

David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.scipy.org/pipermail/scipy-dev/attachments/20070116/915a07a5/attachment.html 


More information about the Scipy-dev mailing list