[SciPy-dev] ndimage - docfiller and output_type

Ralf Gommers ralf.gommers@googlemail....
Thu Oct 29 10:27:57 CDT 2009

Hi Joseph,

I now have a pretty complete implementation.

- 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

>  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

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

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

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

More information about the Scipy-dev mailing list