[SciPy-dev] ndimage - docfiller and output_type

josef.pktd@gmai... josef.pktd@gmai...
Thu Oct 29 11:12:48 CDT 2009


On Thu, Oct 29, 2009 at 11:27 AM, Ralf Gommers
<ralf.gommers@googlemail.com> wrote:
> 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

Thanks, Sounds all very good. I won't have time to look at it though until the
weekend.

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

I thought that's what you did earlier. I will check again.


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

That's very good, no boiler plate to edit.

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

I think only in rv_continuous and rv_discrete docstrings, for those users
that want to look closer, without confusing the user about the basic
usage.


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

For us it should be more like one page description per distribution,
makes 90 pages.
We could add the scripts for the graphs, instead of the actual graphs,
as it is done in the current class docstring.


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

The links are a bit difficult to see, in the second paragraph

http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats/continuous.rst/#continuous-random-variables
http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/stats/discrete.rst/#discrete-random-variables

I think it was Gokhan Sever who converted the lynx docs of Travis to
rst. The first is currently a huge page that takes a long time to
load. It will eventually need to be broken up.

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

Yes, the notes in random are good, in scipy we have more formulas for
the properties of the distributions, that can be calculated using the
distribution methods.
I don't know whether we want to copy or link to the description in numpy.random.

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

Some packages, I have seen, have an almost book length description of
the distributions. The one, I was reading more, was, however,
distributed as a separate pdf file.

>
>>
>> I will be very glad, when we get proper documentation for classes in
>> scipy.
>>

> That will make two of us.

(When you are ready to do the next group, the docs for classes in
interpolate are bothering me for a long time, and several more once I
see a clear pattern how classes and modules should be documented.)

Thanks,

Josef


>
> Cheers,
> Ralf
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>


More information about the Scipy-dev mailing list