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

[Stéfan van der Walt]

2009/6/22 Pauli Virtanen <pav at iki.fi>:
>> We have to decide: is it OK to document the class constructor in
>> __init__?  We used to put this in the class docstring itself so that
>> "help" and IPython's "?" would find it, but I don't think this is longer
>> necessary.  On the other hand, it makes sense: you call "x = MyClass()"
>> to construct, not "x = MyClass.__init__()".  Comments welcome.
>
> IMHO, it would be clearer if the __init__ method was documented
> separately. It can be included on the same page in the Sphinx output as
> the class quite easily. This would allow separate referring to the class
> constructor via eg. :ref:`ndarray <ndarray.__init__>` which might result
> to cleaner documentation.

I wouldn't mind changing this part of the standard.  Robert, I
remember you had a preference last time, do you want to comment?

> The intent of the Methods and Attributes sections in the above scenario
> would mostly be listing the class members that form the API. Descriptions
> given in the Methods and Attributes sections would be ignored in the
> final documentation -- at least for those members that have their own
> docstrings. I wonder if we should allow "See Also"-styled abbreviated
> description lists in these sections?

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.

> I'm not so sure about #doctest: +SKIP lines.

I reverted that change in HOWOT_DOCUMENT.txt for now.

Regards
Stéfan