[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

> 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

> 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.

-------------- 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