[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

[Guido van Rossum]

[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/)