[Python-Dev] query: docstring formatting in python distutils code
C. Titus Brown
ctb at msu.edu
Wed Jul 7 18:12:06 CEST 2010
On Wed, Jul 07, 2010 at 05:09:40PM +0100, Michael Foord wrote:
> On 07/07/2010 17:06, Shashwat Anand wrote:
>> On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown <ctb at msu.edu
>> <mailto:ctb at msu.edu>> wrote:
>>
>> 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?
>>
>> 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.
OK.
I guess docutils isn't in the stdlib (should it be?) or else we could modify
'help' to use it to prepare a straight text formatting.
cheers,
--titus
--
C. Titus Brown, ctb at msu.edu
More information about the Python-Dev
mailing list