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

[Georg Brandl]

Am 07.07.2010 21:52, schrieb Brett Cannon:
> On Wed, Jul 7, 2010 at 10:30, Georg Brandl <g.brandl at gmx.net> wrote:
>> Am 07.07.2010 18:09, schrieb Michael Foord:
>>>>     Hi all,
>>>>
>>>>     over on the fellowship o' the packaging mailing list, one of our GSoC students
>>>>     (merwok) asked about how much formatting info should go into Python stdlib
>>>>     docstrings.  Right now the stdlib docstrings are primarily text, AFAIK; but
>>>>     with the switch to Sphinx for the official Python docs, should we permit
>>>>     ReST-general and/or Sphinx-specific markup in docstrings?
>>
>> I promised to write a PEP about that some time in the future.  (Probably after
>> 3.2 final.)
> 
> For those of you who aren't aware, there actually already is a PEP on
> using reST in docstrings: http://python.org/dev/peps/pep-0287/ .
> 
> But it could stand to be updated by Georg with current practice with
> our internal doc practices as 2002 was back when we were still using
> LaTeX.

Thanks for the reference, Brett.  I do not intend to do my work in PEP 287
(though it probably could be given a few updates, have to look in detail),
but rather refer to it in the new one, since my proposed PEP was less about
actual syntax of reST docstrings than about their use in the standard
library.  As far as I could see, most recommendations from PEP 287 would
apply to them.

Georg