[SciPy-dev] ndimage - docfiller and output_type

[Ralf Gommers]

On Sun, Oct 25, 2009 at 5:27 PM, Matthew Brett <matthew.brett at gmail.com>wrote:

> > Update: someone decided to work on the filters docs last night during the
> > sprint, so the @docfiller markup will be wiped out by the next doc merge
> > unless we decide it is important and fix it.
>
>
> I wrote the original docfiller, so I should probably say that:
>
> For this situation, where there are many functions with the same set
> of parameters, and the parameters require significant explanation, it
> would be good to have some mechanism to keep track of the overlap.


Agreed.

If we separate the docstrings, it's difficult to imagine that they will
> stay in sync, if people are editing them on the doc wiki.


Yes, they won't stay in sync.


> The docfiller pattern is one I'd already used on the matlab IO code, for
> the same reason.


As noted in pydocweb issue 33
http://code.google.com/p/pydocweb/issues/detail?id=33 , it is possible to
support this. But then this needs to be a standard, and the only such way to
manipulate docstrings. I think in scipy.stats there's a different mechanism
already. Could they be unified?


>   I think it's relatively easy to keep track of
> what's going on using SVN, so it would be a shame if we lost the
> ability to sync docstring components by using the wiki...
>

Keeping track is easy, but fixing it by hand each time after wiki merges
will not work. docfiller markup has already been lost.

Could you comment on the flexibility of docfiller? Would it work for
scipy.stats? Would it need a NEP to document its behavior and specify that
this is *the* way to modify docstrings?

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