On Wed, Jul 7, 2010 at 10:30, Georg Brandl <g.bra...@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@python.org > http://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > http://mail.python.org/mailman/options/python-dev/brett%40python.org > _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com