[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

Hi Joseph,

I now have a pretty complete implementation.
http://github.com/rgommers/doctemple/blob/master/newstats.py

Features:
- backwards compatible (see olddefault)
- new default way with only one word of "boilerplate" (see newdefault)
- pdf method descriptions in extradoc ends up in the right place (see wald)
- ability to keep defaults for most elements while adding new sections etc
where wanted (see maxwell)
- rv_continuous can now have a useful docstring for itself, to show how to
subclass it


On Thu, Oct 29, 2009 at 3:33 PM, <josef.pktd@gmail.com> wrote:

>
> I have to look at this again next week when I have a bit more time.
>
> I don't mind the boiler plate code in the individual distributions anymore,
> if we can improve the docs for the distributions this way. You could try
> it out on a few distributions to avoid having to edit 90 templates if there
> are any changes.
>

Will do. Not too much boilerplate anyway. For the common case of a small
class that has only a couple of lines in `extradoc` that describe the
distname.pdf, the number of lines per class is pretty much unchanged. For an
example, see `wald`. Both current trunk and the new version are 18 lines.

>
> Just a quick summary (or wishlist), I agree with most/all of your proposals
>
> * more informative (developer) docstrings for generic rv_continuous
>  rv_discrete
>
ready to go.

* keep individual signature of methods in distribution class docstring
>
done

>  and clarify role of parameters and __call__ for frozen distribution;
>
to be done, straightforward.

>  get links to generic method description
>
will have a look later, but this is a doc build issue


> * two ways of creating doc string (?)
>  - generically generated for distributions nobody wants to edit,
>    including minimal templating for non-scipy subclasses.
>
done, works with no docstring at all, or a one-liner

>  - docstrings with individualized parts, where someone can
>    edit at least notes, example and reference sections
>
done


> * SeeAlso to generic distribution class description and link
>  to distribution in tutorial (?)
>
sure

>  Can we have links to numpy docs for random, but this wouldn't
>  work in a local html or htmlhelp with different files?
>
 numpy.random has already a lot more descriptions for the
>  individual distributions.
>
intersphinx is enabled but doesn't work (i think). Pauli, can you clarify?


> * attach docs to __class__ instead of instance
>
I was not paying attention there. Assigning to __class__.__doc__ only works
for old-style classes. rv_generic inherits from object, so it does not work
then. If this is important to you to fix help() you can always convert to
old-style classes. I had a quick look, and I don't think any of the
old-style / new-style differences matter for stats.distributions.

* ...?
>
> Two more issues:
>
> How much boiler plate do I have to edit if I add a new method to the
> generic classes, rv_continuous, rv_discrete
> or edit an existing one?
>
> Not much. For a new method `xxx` you would add a variable `_doc_xxx`,  then
add that to `_doc_allmethods` and `_doc_afterpdf`. That's it for all classes
that did not write a custom Methods section. For the classes with custom
Methods, you would add "%(xxx)s" in there.

If you edit an existing method, you do not have to do anything.


Maybe it would be good to add an attribute description for a, b,
> numargs and shape to the class docstrings.
>

sure, will do


> In the generic classes, I would also like to document other (and some
> private) methods. Currently starting with underline is not a good
> indication for whether the method is considered private. Several
> private methods are missing the underline, and
> many of the private methods are useful (with some restrictions).
>

makes sense, but you do not want them to show up in the instance docstring
right? maybe only in the rv_continuous and rv_discrete docstrings?


Longer term question:
>
> How much information do we want in the docs about individual
> distributions. e.g. compared to
>
>
> http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/maxcdf.htm
> with some duplication in
>
> http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/maxpdf.htmand
>
> http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/maxppf.htm
>
> That seems a bit too much right? One page for each distribution method = 90
dist * 6 methods = many hundreds of pages.



> and can we induce editors to edit the notes in the distribution
> reference (in tutorial) instead of blowing up the
> notes section in the actual docstring. (following Pierre's
> suggestions). Is there a page limit on the size of the docs?
>
> Do you mean this page:
http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats.rst/? There is no
info there yet on specific distributions.

I like the numpy.random pages, for example
http://docs.scipy.org/numpy/docs/numpy.random.mtrand.RandomState.standard_t/
Maybe one or two paragraphs more, that should be enough for pretty much any
distribution function, or not?

No idea about a page limit, but if you plan on writing more than a page and
a half per distribution, you have enough material for a book.....


> I will be very glad, when we get proper documentation for classes in scipy.
>
> That will make two of us.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20091029/77db5236/attachment.html