[I'm hoping David Goodger is reading this on python-dev. Replying to <user>@users.sf.net doesn't work from my home box. It's my fault but I have no idea how to fix it.]
IOW, reStructuredText is not even an option for new standard library modules.
What about existing docstrings? There is plenty of informal markup in there already.
Yeah, but they're not using any particular formal markup. You'd still have to do a massive, *massive* cleanup if you wanted reST to apply. And it's not clear what the advantage would be -- stdlib docstrings are mostly intended as hints, summarizing the info from the library reference, and as such are intended for presentation *without* additional processing. Minimal though reST is, it's still markup.
For the standard library I would suggest that, once the tools are up to it (e.g., once there's reStructuredText support in pydoc), *existing* docstrings could be *minimally* converted to formalize the implicit markup that's *already there*. For example, here's the module docstring for the string.py module:
"""A collection of string operations (most are no longer used in Python 1.6).
Warning: most of the code you see here isn't normally used nowadays. With Python 1.6, many of these functions are implemented as methods on the standard string object. They used to be implemented by a built-in module called strop, but strop is now obsolete itself.
Public module variables:
whitespace -- a string containing all characters considered whitespace lowercase -- a string containing all characters considered lowercase l uppercase -- a string containing all characters considered uppercase l letters -- a string containing all characters considered letters digits -- a string containing all characters considered decimal digits hexdigits -- a string containing all characters considered hexadecimal octdigits -- a string containing all characters considered octal digit punctuation -- a string containing all characters considered punctuati printable -- a string containing all characters considered printable
"""
(I wrapped the first two paragraphs and truncated the list so email wouldn't wreck it.)
As it stands, this is almost valid reStructuredText (strictly speaking it is already valid, but the list would get wrapped and wouldn't be very useful). The list of variables needs a bit of work; it could be turned into a bullet list or a definition list. The variable identifiers themselves could be marked up as "interpreted text" (e.g. rendered in a different face, with links to each identifier's docstring if it exists). The warning could be left as-is, or spruced up. Here is the fully converted docstring:
"""A collection of string operations (most are no longer used in Python 1.6).
.. Warning:: most of the code you see here isn't normally used nowadays. With Python 1.6, many of these functions are implemented as methods on the standard string object. They used to be implemented by a built-in module called strop, but strop is now obsolete itself.
Public module variables:
`whitespace` a string containing all characters considered whitespace `lowercase` a string containing all characters considered lowercase letters `uppercase` a string containing all characters considered uppercase letters `letters` a string containing all characters considered letters `digits` a string containing all characters considered decimal digits `hexdigits` a string containing all characters considered hexadecimal digits `octdigits` a string containing all characters considered octal digits `punctuation` a string containing all characters considered punctuation `printable` a string containing all characters considered printable
"""
The conversion is minimal (it could be even less), it's still perfectly readable, and the difference in the converted output is significant. Please take a look at the converted output (1 or 2) and compare to the output for vanilla pydoc (3).
1. http://structuredtext.sf.net/spec/string.html 2. http://structuredtext.sf.net/spec/string2.html (bullet list instead of definition list) 3. the first section of http://web.pydoc.org/2.2/string.html
(Note that the HTML uses a CSS1 stylesheet, so a recent browser is required. A writer for HTML for older browsers is on the to-do list.)
In any case, nothing needs to be done any time soon. What do you think?
Alas, I find both the input and the output of the reST-ized version worse than the original. The original takes up much less vertical space, which (given the goal of being a relatively terse hint rather than formal reference docs) counts for more than bullets, boxes and color. The situation would be different if the goal was to replace the reference docs, but since it isn't, I think the informal markup is just fine. --Guido van Rossum (home page: http://www.python.org/~guido/)