[SciPy-dev] ndimage - docfiller and output_type

[Matthew Brett]

Hi,

> As noted in pydocweb issue 33
> http://code.google.com/p/pydocweb/issues/detail?id=33 , it is possible to
> support this. But then this needs to be a standard, and the only such way to
> manipulate docstrings. I think in scipy.stats there's a different mechanism
> already. Could they be unified?

[see below]

>>   I think it's relatively easy to keep track of
>> what's going on using SVN, so it would be a shame if we lost the
>> ability to sync docstring components by using the wiki...
>
> Keeping track is easy, but fixing it by hand each time after wiki merges
> will not work. docfiller markup has already been lost.

Yes, right...

> Could you comment on the flexibility of docfiller? Would it work for
> scipy.stats? Would it need a NEP to document its behavior and specify that
> this is *the* way to modify docstrings?

Ah - now you're asking me to think, on a Sunday morning.

Just a review for those not reading the code for pleasure:

docfiller does this: (scipy.ndimage.doccer, scipy.ndimage.filters):

# give docstrings for particular parameters as dictionary values.
# usually they will be multi-line of course
docdict = {'param1': 'param1 : int, optional', 'param2': 'param2 :
bool, optional'}
# make a decorator to fill in those strings when they appear in the docstring
docfiller =  doccer.filldoc(docdict)
# use decorator...
@docfiller
def func(param1=0, param2=False):
    """ A function to do things

    Parameters
    ----------------
    %(param1)s
    %(param2)s
    ''''
    pass

scipy.stats (sorry I read this fast) does a similar thing by defining
an object to contain a particular type of distribution function (e.g
rv_continuous), and you can pass things like the function short and
long names, allowable input shape and any extra text you want to add
to the docstring, and the object __init__ fills the docstring for you.

Docfiller allows you to enter any repeated piece of text, requiring
you only to define the %(text_here)s placeholders.  scipy.stats in
docfiller flavor would be:

docdict = {'name': 'normal', 'longname': 'the Gaussian (normal)
distribution'} # etc

scipy.stats does some processing of the input parameters like shape,
to determine the docstring, but that could easily be put in your
decorator.

So, I'm not sure docfiller is the only or best solution, but it looks
like something like it recurs in the code, and I think it could work
for scipy.stats...

See you,

Matthew