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

Brett Cannon brett at python.org
Wed Jul 7 21:52:26 CEST 2010

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

More information about the Python-Dev mailing list