[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

On Mon, Oct 26, 2009 at 12:00 AM, Ralf Gommers
<ralf.gommers at googlemail.com>wrote:

>
>
> On Sun, Oct 25, 2009 at 11:11 PM, <josef.pktd at gmail.com> wrote:
>
>> 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
>> >
>> >>
>> >> 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
docstring, but add custom descriptions where necessary, add sections, links,
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.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091028/5c3d689f/attachment.html>