[SciPy-Dev] distribution docstring generation

[Ralf Gommers]

On Sat, May 15, 2010 at 4:38 PM, David Goldsmith <d.l.goldsmith at gmail.com>wrote:

> On Sat, May 15, 2010 at 12:38 AM, Ralf Gommers <
> ralf.gommers at googlemail.com> wrote:
>
>>
>> On Sat, May 15, 2010 at 1:03 PM, David Goldsmith <d.l.goldsmith at gmail.com
>> > wrote:
>>
>>>
>>> I'm not entirely clear on the template problem to which you refer, but
>>> perhaps looking at what I did for Polynomial.deriv (actually, all of
>>> Polynomial's and Chebyshev's methods) might help?  In particular, both of
>>> these classes are generated from a template, and so things in the docstring
>>> that need to be substituted with the "value" of the template (i.e., either
>>> Polynomial or Chebyshev) are named w/ "$name" (and references to similar
>>> functions that use only a portion of the name use a ${nick}<rest of function
>>> name> syntax); I don't know if this a universal feature of the Python
>>> templating system, however - Charles H.?
>>>
>>> Hmm, I hadn't seen that before, it's a different method from used in
>> scipy.stats/ndimage.
>>
>> Sorry to have to say this, but those changes are not very useful.
>>
>
> Please explain/elaborate.
>

I mean it would take someone else a lot of time to review this and get it
into svn, and it's not likely someone will actually take that time IMHO.

>
>
>> Those pages should also be locked and not edited.
>>
>
> Well, yes, if the Wiki supported editing the template's docstring, but it
> doesn't, so...
>
>
>> The generated patches will be nonsense, and copying over cosmetic changes
>> like in Polynomial.deriv manually is a lot of work.
>>
>
> Well, that would appear to be a price we pay for using templating.
>

No, same answer as above. Just don't use the wiki for these docstrings until
it supports the template system (which it perhaps never will).

>
>
>> If you really want to make minor changes to those templates,
>>
>
> IIRC, not all of my changes were minor.
>
> I suggest you provide a proper patch
>>
>
> I.e., a source code patch?
>

Yes.

>
>
>> or github branch and ping Charles to review/apply them.
>>
>
> I believe in general, to the extent possible, we want independent eyes to
> be reviewing docstrings (i.e., neither the code nor the docstring author),
> yes?
>
> Ideally, yes. But that doesn't mean reasonable changes can't be applied
before an independent review.

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