[Python-Dev] query: docstring formatting in python distutils code (original) (raw)

Martin Geisler mg at aragost.com
Fri Jul 9 13:40:05 CEST 2010

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/

More information about the Python-Dev mailing list