[SciPy-user] Docstring standards for NumPy and SciPy

[Neal Becker]

Gael Varoquaux wrote:

> On Thu, Jan 11, 2007 at 03:42:18PM -0700, Brian Granger wrote:
>> This would be really nice and address the line noise issue - at least
>> within ipython.  I'm sure it could be done as epydoc just uses
>> docutils to parse the docstrings.  I don't know much about the
>> docutils internals, but I am assuming you could access the document
>> tree of the doc string and then print things however you want.  This
>> would be rather cool and could be done dynamically on the fly.
> 
> I can volonteer to implement this, if nobody is in too much of a hurry (I
> am quite busy currently). I have a bit of experience with the docutils.
> 
> On the other hand, docutils are pretty simple to understand, so I guess
> any regular contributor to scipy could do this.
> 

I'd just like to add, that a number of posts have advocated for a design
where docstrings are read via parsing instead of introspection. 
Unfortunately, we need to document objects written in languages other than
python (C, C++).  A hybrid system is possible (use parsing when possible,
revert to introspection), but a system that only uses parsing doesn't meet
the requirements.