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 <ctb at msu.edu >> <mailto: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 - >> 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, ctb at msu.edu
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4