[SciPy-user] improving docs for classes was: Re: scipy.interpolate spline class names

[josef.pktd at gmail.com]

I'm changing the thread title.

On Fri, May 22, 2009 at 9:03 PM,  <josef.pktd at gmail.com> wrote:
> On Fri, May 22, 2009 at 8:24 PM, Pauli Virtanen <pav at iki.fi> wrote:
>> Fri, 22 May 2009 19:22:14 -0400, josef.pktd wrote:
>> [clip]
>>> There is also still the open question how we get the information of the
>>> docstrings in class.__init__ into the sphinx docs.
>>
>> The Numpy docstring standard dictated that the __init__ method should be
>> documented in the main class docstring.
>>
>> I don't personally like this very much. Maybe we need to revise this?
>>
>> Anyway, the Sphinx dev version contains an improved version of
>> autosummary that has features that could be used to address this.
>>
>>   ***
>>
>> So I'd suggest currently just making a separate hand-written page for the
>> interpolation class docs, making appropriate use of the autoclass:: and
>> automethod:: directives.
>>
>> The main documentation page interpolate.rst could then contain the
>> corresponding autosummary directives without the :toctree: argument.
>>
>> --
>> Pauli Virtanen
>
> Pauli,
> do you have an example how to do this? when I tried autoclass and
> automethod in the doc editor then it didn't produce the intended
> results.
>
> For example for the KroghInterpolator:
> Given last years discussion a lot of information was put into the __init__
>
> What I would find very helpful would be if the link for
> KroghInterpolator in
> http://docs.scipy.org/scipy/docs/scipy-docs/interpolate.rst/  leads to
> the full autodocs of the class, with all or selected automethods. I
> would  prefer one page per class for the class based modules such as
> the interpolator classes.
>
> I find the docs very well structured and accessible for functions but
> in many cases it doesn't provide a good structure for classes.
>
> If you have an example for how this can be done, then I could fix
> parts of the docs. The numpy docstring doesn't really define the
> structure for the sphinx documentation, or does it.
>
> I still appreciate the htmhelp files for windows a lot. It's very
> useful to have instantaneous search and access to the docs. That's why
> it's bugging me when the information is not in the docs, even though
> it can be accessed with >>> help(classname). But currently the docs
> don't produce the same result.
>

some more on the current status of the documentation of classes:

The __call__ method also seems to be a second class citizen, not only
in interpolate. I assume it is not automatically included in the
autodoc. I just checked scipy.stats.rv_continuous and
stats.kde.gaussian_kde. rv_continuous mentions the __call__ method in
the class docstring, but there is no further reference,
stats.kde.gaussian_kde is silent about it's __call__ methods

Also the class docstrings don't link to or list the methods. For
example rv_continuous lists all the important methods but there are no
links.
Additional to the classes in scipy, I checked numpy.DataSource and
numpy.random.RandomState, and the help page for them is pretty
uninformative, I don't know and cannot link to any of their methods.

compare this for example with  help(numpy.DataSource)

I hope that by the end of this years gsoc, we will be adding many
stats.model classes. So a good documentation pattern for classes would
be very helpful for us. And if we allow for different array subclasses
in the __init__ method, then we need the facility to document them. A
similar example is scipy.signal.lti which allows 3 different
constructors, see the doc page at
http://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.lti.html#scipy.signal.lti

I don't know whether this just needs some additional rst files,
changes in the automatic document creation or in the docstring
standard.

Of course there is the way of writing full rst docs as in
http://docs.scipy.org/numpy/source/numpy/doc/source/reference/arrays.ndarray.rst,
but that looks like a lot of additional work, which might not happen
very soon.

So I think that for small to medium sized classes we should find a way
to create automatic class documentation including special methods
__init__ and __call__ and maybe others, if these methods have a
special meaning. __init__ is useful if we want to describe the
constructor in more detail instead of copying all information into the
class docs or to separate rst files.

I'm still stuck getting members or methods added to an autoclass
directive: http://docs.scipy.org/scipy/docs/scipy-docs/interpolate_UnivariateSpline.rst/

Josef