[Python-Dev] query: docstring formatting in python distutils code (original) (raw)

C. Titus Brown ctb at msu.edu
Wed Jul 7 18:08:24 CEST 2010

On Wed, Jul 07, 2010 at 09:36:10PM +0530, Shashwat Anand wrote:

On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown <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 - h ttp://cl.ly/c5bb3be4a01d9d44732f So will it be ok to break them ?

I don't understand...

Frist, you can already use

help(os.getcwd)

to get the same result.

Second, what would we be breaking? We'd be making the straight text representation a bit more cluttered in return for adding certain kinds of meta-information into the markup. I think it's a judgement call...

cheers, --titus

C. Titus Brown, ctb at msu.edu

More information about the Python-Dev mailing list