[SciPy-dev] ndimage - docfiller and output_type
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 <firstname.lastname@example.org>
>> On Sun, Oct 25, 2009 at 11:11 PM, <email@example.com> wrote:
>>> On Sun, Oct 25, 2009 at 5:33 PM, Ralf Gommers
>>> <firstname.lastname@example.org> wrote:
>>> > On Sun, Oct 25, 2009 at 8:20 PM, Matthew Brett
>>> > <email@example.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
>>> 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.
> pdf(x, loc=0, scale=1)
> Probability density function. Given by
> :math:`\sqrt(2/pi)*x^2 * exp(-x**2/2)` for ``x>0``.
> 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 _.
> ..  http://mathworld.wolfram.com/MaxwellDistribution.html
> 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
> Try this with:
> In : run newstats.py
> In : 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
no difference in the docstring of the class:
>>> print stats.distributions.norm_gen.__doc__
>>> print distname_gen.__doc__
>>> 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__
> Scipy-dev mailing list
More information about the Scipy-dev