[Python-Dev] query: docstring formatting in python distutils code

[Martin Geisler]

Georg Brandl <g.brandl at gmx.net> writes:

> Am 08.07.2010 17:44, schrieb Martin Geisler:
>> Steve Holden <steve at holdenweb.com> writes:
>> 
>>> Martin Geisler wrote:
>>>> "Stephen J. Turnbull" <stephen at xemacs.org> writes:
>>>> 
>>>>> Just ask Martin, there are too many possibilities here to worry
>>>>> about. If maybe we want it, and he is willing to contribute the
>>>>> parts he wrote to Python under Python's license, then we can worry
>>>>> about whether we really want it and about how much any required
>>>>> hoop-jumping will cost.
>>>> 
>>>> I would be happy to relicense it under the Python license.
>>>
>>> I believe the ideal outcome, if it is possible, is for you to sign a
>>> contributor agreement. This will license your material to the PSF in
>>> such a way that we can release it under whatever license we deem
>>> necessary.
>> 
>> Sure, I'll be happy to sign a contributor agreement if you guys think it
>> worthwhile to use my little parser and formatter.
>
> Problem is, in the case of help() we have no way of knowing whether the
> given __doc__ string is supposed to be (mini)reST.  Of course, reverting
> to showing the plain content on parsing errors is one possibility, but
> I can still imagine instances where something is successfully interpreted
> as reST, but intended to be read and understood verbatim by the author.

The minirst module is actually designed to never fail: the text is first
divided into paragraphs, and the paragraphs are then looked at one by
one to see if they look like something more specific like a list.

> It's different for Hg, of course, there you can just decide that help
> texts have to be reST.

Right, good point. At first I figured that you could also "just" convert
the docstrings in Python, but since the help builtin is used on lots of
code outside of Python this isn't really enough.

-- 
Martin Geisler

aragost Trifork -- Professional Mercurial support
http://aragost.com/mercurial/