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

[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.

-Brett

>
>>>     Hmm, I don't actually see that the stdlib docstrings are imported into the
>>>     Python documentation anywhere, so maybe the use of Sphinx isn't that
>>>     relevant.  But how about ReST in general?
>>>
>>>
>>> So will we be able to use .__docs__ within python interpretor, which is quite
>>> handy feature.
>>> >>> print(os.getcwd.__doc__)
>>> getcwd() -> path
>>>
>>> Return a string representing the current working directory.
>>> Also some python interpretors like bpython uses it ; a snapshot here -
>>>  http://cl.ly/c5bb3be4a01d9d44732f
>>> So will it be ok to break them ?
>>
>> Using ReST won't *break* these tools, but may make the output less readable.
>>
>> 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.
>
> cheers,
> Georg
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org
>