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

Ralf Gommers ralf.gommers@googlemail....
Mon Jun 22 16:32:04 CDT 2009


On Mon, Jun 22, 2009 at 4:41 PM, <josef.pktd@gmail.com> wrote:

> On Mon, Jun 22, 2009 at 3:11 PM, Ralf
> Gommers<ralf.gommers@googlemail.com> wrote:
> >
> >
> > On Mon, Jun 22, 2009 at 12:19 PM, Robert Kern <robert.kern@gmail.com>
> wrote:
> >>
> >> 2009/6/22 Stéfan van der Walt <stefan@sun.ac.za>
> >> >
> >> > 2009/6/22 Pauli Virtanen <pav@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?
> >>
> >> I have always preferred documenting the __init__'s Parameters in the
> >> class docstring because one calls the class object itself.
> >
> > I prefer this as well. Why make it more complicated unless there's a good
> > reason?
> > Also, IPython will maybe still be able to do the right thing if both
> class
> > and __init__ are documented, but the standard Python prompt's help()
> > function will not. And there are still a lot of users of the standard
> > prompt, simply because it's the standard.
>
>
> pythons help is actually very informative but our documentation is
> not. Whatever the decision, we should adjust the current docstrings so
> that they actually get included in the generated docs.
> E.g. scipy.interpolate: after last years discussion a large part of
> the information is only available as docstring to the __init__ method.
> If we stick with documenting the constructor in the class docstring,
> then we should move them.
>

scipy.interpolate is a module, so I assume you mean the classes in it. For
some classes it is done correctly (see interp2d), other classes have both
class and constructor documented (see interp1d). Doc writing has mainly
concentrated on numpy so far, and there I have not come across classes with
both class and constructor being documented.
I agree it would be very useful for someone to go through scipy modules and
move things around.


> As an enhancement to the doc editor, it would be nice if it would also
> show the generated documentation from an autoclass directive. This
> would reduce the guessing about whether and how the docstrings will
> show up.


agreed

>
>
> How do we treat other class specific headers?
> e.g "Internal Methods" in
> http://docs.scipy.org/scipy/docs/scipy.stats.kde.gaussian_kde/


Internal Methods is not a part of the documentation standard. Was this
discussed on the list last year? I thought the consensus was that methods
that are part of the API go under Methods, the rest is not listed in the
class docstring.

Ralf


>
> I hope some nice examples come out of this, so we can include some of
> the left out class documentation in scipy without a lot of guessing.
>
> Josef
>
> >
> >>
> >> --
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20090622/d66107a9/attachment-0001.html 


More information about the Scipy-dev mailing list