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

[Ron Adam]

On 07/07/2010 12:30 PM, Georg Brandl wrote:
> Am 07.07.2010 18:09, schrieb Michael Foord:
>
>> I would say that the major use of docstrings is for interactive help - so
>> interactive readability should be *the most important* (but perhaps not only)
>> factor when considering how to format standard library docstrings.
>
> Agreed.  However, reST doesn't need to be less readable if the specific
> inline markup is not used.  For example, using `identifier` to refer to a
> function or *var* to refer to a variable (which is already done at quite a
> few places) is very readable IMO.  Using ``code`` also isn't bad, considering
> that double quotes are not much different and potentially ambiguous.
>
> Overall, I think that we can make stdlib docstrings valid reST -- even if it's
> reST without much markup -- but valid, so that people pulling in stdlib doc-
> strings into Sphinx docs won't get ugly warnings.
>
> What I would *not* like to see is heavy markup and Sphinx specifics -- that
> would only make sense if we included the docstrings in the docs, and I don't
> see that coming.

I also agree that interactive help should be the most important factor when 
writing doc strings for the standard library.

Are there any plans to change how pydoc's GUI mode works?  Could it use a 
minimal set of reST to improve it's display?

The patch I submitted (*which is waiting to be reviewed) extends the GUI 
mode so it can show the same info that is available from the help() function.

	http://bugs.python.org/issue2001

I think the only issues with this patch are what new functions and classes 
should be part of the public api.


* BTW... The bug trackers main links to items with patches, and needing 
review, doesn't pick up feature requests.

Ron