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 <c...@msu.edu >> <mailto:c...@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, c...@msu.edu _______________________________________________ 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
