# [SciPy-dev] ndimage - docfiller and output_type

josef.pktd@gmai... josef.pktd@gmai...
Wed Oct 28 08:52:37 CDT 2009

On Wed, Oct 28, 2009 at 8:10 AM, Ralf Gommers
>
>
> On Mon, Oct 26, 2009 at 12:00 AM, Ralf Gommers <ralf.gommers@googlemail.com>
> wrote:
>>
>>
>> On Sun, Oct 25, 2009 at 11:11 PM, <josef.pktd@gmail.com> wrote:
>>>
>>> On Sun, Oct 25, 2009 at 5:33 PM, Ralf Gommers
>>> >
>>> >
>>> > On Sun, Oct 25, 2009 at 8:20 PM, Matthew Brett
>>> > <matthew.brett@gmail.com>
>>> >>
>>> >> 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.
>>
>> For scipy.stats it might not be any better than the current method, but it
>> also would not be worse. The point is that it will be a lot of work to make
>> the wiki play nice with even *one* templating system.
>>
>> Since a decorator is more widely applicable than the scipy.stats
>> inheritance, it could be a good candidate to be applied everywhere in
>> NumPy/SciPy and be recognized by pydocweb.
>>
>
> Hi Josef and others,
>
> I have got a prototype of a more flexible docstring system for
> scipy.stats.distributions working, based on the same string substitution as
> used in ndimage and io.matlab. I looked at improving the current template as
> well, but it is simply not possible to get very good results when you
> generate lots of docstrings from a single generic string with a few words
> swapped in for placeholders.
>
> The new system is backwards-compatible, meaning the current way of
> generating docstrings from a generic template continues to work if the
> distname_gen class does not have its own docstring. So no extra work for
> the people working on scipy.stats to change things around.
>
> The way it works is that you can use defaults for most elements of a
> references, etc. An example:
>
>     """A Maxwell continuous random variable.
>
>     Methods
>     -------
>     %(rvs)s
>     pdf(x, loc=0, scale=1)
>         Probability density function. Given by
>         :math:\sqrt(2/pi)*x^2 * exp(-x**2/2) for x>0.
>     %(cdf)s
>     %(sf)s
>     %(ppf)s
>     %(isf)s
>     %(stats)s
>     %(entropy)s
>     %(fit)s
>
>     Notes
>     -----
>     A special case of a chi distribution,  with df = 3, loc = 0.0,
>     and given scale = 1.0 / sqrt(a), where a is the parameter used in
>     the Mathworld description [1]_.
>
>     References
>     ----------
>     .. [1] http://mathworld.wolfram.com/MaxwellDistribution.html
>
>     Examples
>     --------
>     %(default_example)s
>
>     """
>
>
> The code can be found at http://github.com/rgommers/doctemple. The
> oldstats.py file shows the basics of how docstring generation currently
> works in scipy.stats.distributions, and newstats.py contains the new
> functionality.
>
> Try this with:
> In [1]: run newstats.py
> In [2]: maxwell?
>
> Please let me know what you think.

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.

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

(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?
The template substitution is still in the rvclass.__init__

Thanks,

Josef

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