[SciPy-dev] ndimage - docfiller and output_type

[josef.pktd at gmail.com]

On Wed, Oct 28, 2009 at 4:16 PM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
>
>
> On Wed, Oct 28, 2009 at 8:34 PM, <josef.pktd at gmail.com> wrote:
>>
>> On Wed, Oct 28, 2009 at 2:07 PM, Pauli Virtanen <pav+sp at iki.fi> wrote:
>> > Wed, 28 Oct 2009 11:13:10 -0400, josef.pktd wrote:
>> > [clip]
>> >> 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.
>> >
>> > Then, I'd suggest just adding
>> >
>> >        %(info)s
>> >
>> > or so, that will be expanded to the full boilerplate information block.
>> > Then, only this would be repeated in each distribution docstring -- not
>> > too bad.
>>
>> If you can do it with minimal code/text duplication, then any way is fine
>> with me.
>>
> Okay, I'll come up with a patch with as little duplication as possible (one
> line per distribution).
>
>>
>> >
>> > It is clearer and cleaner if the distribution docstring is a template,
>> > resides in the class docstring, and the final product is assembled by
>> > substitution rather than by concatenating magically generated parts.
>> > (Think, for example -- why are HTML templating languages so popular, as
>> > opposed to just concatenating blocks of HTML code?)
>>
>> The last time I looked at mako, it allowed full inheritance and backward
>> (?)
>> substitution in the templates.
>>
>> I don't see how template inheritance would work with simple string
>> substitution, but you are the experts for the numpy/scipy documentation
>> system.
>
> Inheritance is the wrong word. The idea is to build up a docstring from
> smaller pieces, instead of starting with one big template and then trying to
> change it. In the default (simplest) case, you build up a string in the
> module scope, only substitute <shapes> for each distribution, and assign it
> to __doc__.
>
> Cheers,
> Ralf

I like your initially proposed solution, because it allows both ways, either
full generic template (for distributions that nobody looks at), or following
the maxwell pattern for the distributions, where someone would want to
add individualized information.

One other advantage of the generic docstring is that it is easy to create new
classes outside of scipy by subclassing rv_continuous and have the docstring
generated the same way as distribution in scipy.

But even having your basic template is not really a problem, it's mainly
the numpy docstring standard and the template is not something we would
have to edit often.
(It would still double the lines of code for many distributions).

I still like to keep name and (maybe) longname since they are used in
programs, if I remember correctly.
Personally, I like extradoc, that's the only really interesting information
about a distribution that I look at (besides dist.a and dist.b and dist.shape.)
and I don't have to scroll through the boiler plate docstring to read it.

(In general, I think the class should get the default constructor information
in the __init__ method instead of in the instantiation.)

Josef




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