[SciPy-dev] Doc-ing classes and data attributes

[Pauli Virtanen]

Mon, 22 Jun 2009 12:23:18 +0200, Stéfan van der Walt kirjoitti:
[clip: Attributes, Methods]
> It's unfortunate that we need to fill these sections in by hand.  We
> could auto-generate them for the Sphinx docs, but then the terminal
> users would still be stuck.

help(ndarray) does list all the methods and properties, though not 
necessarily all attributes.

Not all visible attributes or methods in a class are a part of the API, 
though, and some are unimportant for the use of the class. Also, some but 
not all __special__ methods may be important. I don't think there is an 
easy way to automatically decide which methods to include and which not, 
so IMHO writing this part manually is an important element in making sure 
that the documentation makes sense. (As opposed to eg. epydoc-generated 
lists full of irrelevant details.)

I wonder: should the format allow lists to be interspersed with 
commentary, so that attributes etc. could be grouped sensibly?

-- 
Pauli Virtanen