[SciPy-dev] ndimage - docfiller and output_type

[josef.pktd at gmail.com]

On Sun, Oct 25, 2009 at 5:33 PM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
>
>
> On Sun, Oct 25, 2009 at 8:20 PM, Matthew Brett <matthew.brett at gmail.com>
> wrote:
>>
>> Ah - now you're asking me to think, on a Sunday morning.
>>
> Sorry. Hope it wasn't too painful :)
>>
>> 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.
>>
> Okay, now it makes sense to me. The scipy.stats docs are pretty much
> completely auto-generated, even the examples. Then the "extradoc" keyword
> contains extra info that is just tacked on at the end (below the examples).
> There seems to be room for improvement there.
>
>> 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...
>
> Thanks Matthew. Searching for how other people/projects solve this same
> problem I found nothing much fancier than docfiller, so I think I will try
> to get an idea first of how much work it will be to change the scipy.stats
> docs to use docfiller throughout.
>
> Then of course it would be good to hear from Pauli roughly how much work it
> would be to support this in pydocweb. The ticket says "rewrite of
> pydoc-tool.py" so it may be non-trivial....
>
> Cheers,
> Ralf

One of the differences between ndimage and stats.distributions is that in
ndimage  functions are decorated, while the individual distributions (kind of)
inherit the adjusted docstring from the basic distribution classes.

The documentation can be improved (maybe with better templating as in the
ndimage decorator), and I don't know how pydocweb can
handle it, but I don't think we need to start to decorate individual
distributions
when we can use the class hierarchy for generating the docs.

One useful enhancement to the distribution docs would be to get autogenerated
links to the description of the individual distributions that has been
added to the
scipy.stats.tutorial.

Josef


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