[SciPy-dev] documenting objects in stats.distributions
Wed Dec 16 08:03:46 CST 2009
On Wed, Dec 16, 2009 at 6:59 PM, Christopher Burns <email@example.com>wrote:
> On Wed, Dec 16, 2009 at 2:00 PM, Ralf Gommers
> <firstname.lastname@example.org> 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
> > 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
> cburns@stats 14:41:24 $ grin '\(rv_continuous\)' distributions.py | wc -l
> 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...
More information about the SciPy-Dev