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.) >> 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/archive%40mail-archive.com
