[Python-Dev] query: docstring formatting in python distutils code
Georg Brandl
g.brandl at gmx.net
Wed Jul 7 19:30:49 CEST 2010
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.)
>> 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
More information about the Python-Dev
mailing list