[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

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<pav%2Bsp 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091028/45f8e1f7/attachment.html>