[SciPy-dev] ndimage - docfiller and output_type

[josef.pktd at gmail.com]

On Wed, Oct 28, 2009 at 10:41 AM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
> Thanks for the feedback Josef.
>
> On Wed, Oct 28, 2009 at 2:52 PM, <josef.pktd at gmail.com> wrote:
>>
>> Just some quick comments (I will look more after Friday)
>>
>>
>> I don't see a big break with the current system, but the templating
>> system looks cleaner.
>
> Well I did not want to be too radical, just make it a bit more flexible and
> better-looking:)
>>
>> One difference: standard help doesn't get the substitution in the
>> docstring
>> >>> help(maxwell)
>> >>> maxwell.__doc__
>> >>> help(stats.distributions.norm)
>>
>>
>> no difference in the docstring of the class:
>> >>> print stats.distributions.norm_gen.__doc__
>> None
>> >>> print distname_gen.__doc__
>> None
>> >>> print maxwell_gen.__doc__
>> ...
>>
>> Is it possible to attach the docstring to the distribution (sub) class
>> when it is instantiated, e.g.
>>
>> self.__class__.__doc__ = generated docs # I didn't try this
>
> That works, good point. Fixes the python help() as well.
>
>>
>> (The current dist_gen classes are missing a __init__, so the class
>> doesn't get any of the information.)
>>
>> So, I think overall it looks pretty good.
>> Does it really make the life for the doceditor easier?
>
> It should do in the future, but right now that is just an added benefit.
> More important is that you just get better docstrings.
>
>>
>> The template substitution is still in the rvclass.__init__
>
> This can disappear once all classes have their own docstring. I was being
> conservative by keeping the old system as a backup.
>
> If you would be happy if I gave each `_gen` class a default docstring based
> on the new system, and completely remove the templates in
> rv_continuous/rv_discrete, I will do that.

No, I like the current system where we don't have any boiler plate in the
individual distributions. Following your maxwell example, we would get
a lot of repetition of template code in the individual distributions.

I wouldn't mind adding some additional individualized docs similar to the
extradoc to the distribution classes.
Pierre thinks that we should keep it separate.
If we can link to the full description of the distributions, which is currently
stored in the tutorial, then we can have some basic docstring on the
command line, and for additional information we can follow the link.

One problem we still have with the examples in the docstrings is that they
don't always work, since they are too generic and some values might not
be feasible.

Maintaining 90 individual distributions without a generic framework is too
much work. However, with the increased flexibility with your changes,
we could think about individual docstrings for the most popular distributions,
normal, t, ..?

Thanks for improving this.

Josef

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