[SciPy-dev] documenting objects in stats.distributions

Ralf Gommers ralf.gommers@googlemail....
Wed Dec 16 08:03:46 CST 2009


On Wed, Dec 16, 2009 at 6:59 PM, Christopher Burns <cburns@berkeley.edu>wrote:

> On Wed, Dec 16, 2009 at 2:00 PM, Ralf Gommers
> <ralf.gommers@googlemail.com> wrote:
> > No, to remove the warning pydocweb (the wiki app) should recognize the
> > Methods section in class instance docstrings I think.
> >
> > A related point: the docstrings for the stats distributions are generated
> > from a template right now, so any edits for those docstrings in the doc
> wiki
> > can not be merged without a lot of tweaking. If you're also interested in
> > working on other areas of the scipy docs, that might be more effective.
>
> pydocweb doesn't appear to recognize the Methods section in the
> instance docstrings.   Looking at the code I see that the classes we
> were editing all subclass rv_continuous.  So if we update the
> docstring for rv_continuous, like to have spaces between parameters,
> then that will propagate to the children, is that correct?
>

That is right, but that template should disappear any day now. I spent some
time on a patch to build up all docstrings in stats.distributions in a more
flexible way (I also fixed up the spaces issues etc already). Josef has
already reviewed and will apply the changes when he can (I think). See
http://projects.scipy.org/scipy/ticket/1055


>
> I see there are 80 children:
> cburns@stats 14:41:19 $ pwd
> /Users/cburns/src/scipy-trunk/scipy/stats
> cburns@stats 14:41:24 $ grin '\(rv_continuous\)' distributions.py | wc -l
>      80
>
> I've only looked at a few of the child classes, but in each of those
> the instance docstring displays the warning about the Methods section.
>  Glancing at the pydocweb source I'm wondering if it's mapping these
> docstrings to a NumpyFunctionDocString?  The NumpyFunctionDocString
> docstrings don't have a Method section.
>
> Not sure there. I think Pauli is the only real expert on pydocweb. But
while you're looking at it, if you see a way to fix it that would be
awesome.


> Since so many of these inherit their docstring from a parent class, is
> it possible to show that fact on the documentation editor page?
> Otherwise people will make the same mistake we made and edit the
> generated docstrings instead of the template.
>

One of the admins might be able to do this, but editors/reviewers can not
apply changes to multiple pages at once. I realized before a warning like
this could be handy (or a "no edit" flag or similar), but manually going
through so many pages is a real pain.

While we're at it, other docstrings that are not yet handled well in the doc
editor are those of ndimage.filters. It's better than stats.distributions
but also requires tweaking.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20091216/8eef2988/attachment.html 


More information about the SciPy-Dev mailing list