[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

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.


> 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.
>

Yeah, that would help. Linking to .rst files in general could be improved
still.

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