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

[Ralf Gommers]

On Mon, Jun 22, 2009 at 6:45 PM, <josef.pktd at gmail.com> wrote:

> On Mon, Jun 22, 2009 at 5:32 PM, Ralf
> Gommers<ralf.gommers at googlemail.com> wrote:
> >
> >
> > On Mon, Jun 22, 2009 at 4:41 PM, <josef.pktd at gmail.com> wrote:
> >>
> >> On Mon, Jun 22, 2009 at 3:11 PM, Ralf
> >> Gommers<ralf.gommers at googlemail.com> wrote:
> >> >
> >> >
> >> > On Mon, Jun 22, 2009 at 12:19 PM, Robert Kern <robert.kern at gmail.com>
> >> > wrote:
> >> >>
> >> >> 2009/6/22 Stéfan van der Walt <stefan at sun.ac.za>
> >> >> >
> >> >> > 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?
> >> >>
> >> >> 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.
>
> interp1d, KroghInterpolator and family, UnivariateSpline and family:
> all the constructor information is in the __init__ docstring.
>
> I'm going through scipy myself, but I haven't seen any clear pattern
> for good class documentation yet. But if the consensus is to stick
> with adding all information into the class docstring, I will start to
> move them in interpolate, and clean up the others as I stumble upon
> them.


There are very few classes that have made it to "Needs review" yet, and most
of the ones that did are quite simple. For one of the better examples, see
http://docs.scipy.org/numpy/docs/numpy.ndarray/ It's not done yet, but when
the list of attributes is removed (it is the same as Properties at the
bottom) and the Methods and Properties would show the one-line summary (with
some preprocessor magic), I would consider it a good example.


>
>
> just another random choice for class documentation: I just tried to
> understand what numpy.poly1d is as a class, e.g. attributes and
> methods.
> It has good examples in the class docstring, but what are the methods,
> what is p.r and p.c? (try to find it without looking at the source)
>

Wow, that is obscure. The two public methods are "deriv" and integ". As for
p.c and p.r, I had to look for a while in the source even. They also don't
show up in IPython with tab completion, because of the way it is coded with
__getattr__ magic. I think the message is: do not code it like this unless
there is a very good reason. Why not just:

def roots(self):
    return roots(self.coeffs)

The alias 'r' for 'roots' is not very helpful (but is maybe there for
historical reasons). If it would be coded like the above, it would
automatically show up in the list of methods.

>
>
> What if we want to document some private methods? What's the
> corresponding header to "Other Parameters" for other methods?
>

Private methods have docstrings, which is where they are explained. If you
document them in the class docstring, they show up for the user. Why would
you want to do that (they are private for a reason)?


> And I would still like to see heavier use of autoclass at least in the
> html and htmlhelp doc, with classes and methods on one page.
>

agreed. maybe not the full method docstrings but at least the summary.

>
> I hope your effort on the numpy docs will create some improvement to
> the class documentation, so I can use the help file also for classes
> instead of reading the source.


I hope so too.

>
>
> Just to emphasize it again, the htmlhelp for numpy and scipy is really
> great, instantaneous access to most of the documentation. (I wish some
> other packages, like matplotlib, would provide it also, instead of
> (*args, *kwargs) popup signatures.)
>
> Josef
>
>
> >
> >>
> >> 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
> >>
> >> >
> >> >>
> >> >> --
> >
> > _______________________________________________
> > Scipy-dev mailing list
> > Scipy-dev at scipy.org
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >
> >
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090622/f89b0782/attachment.html>