[Python-Dev] query: docstring formatting in python distutils code
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