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.
Michael
See
http://sphinx.pocoo.org/markup/index.html
for sphinx-specific markup constructs.
thanks,
--titus
--
C. Titus Brown, c...@msu.edu <mailto: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/fuzzyman%40voidspace.org.uk
--
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog
READ CAREFULLY. By accepting and reading this email you agree, on behalf of your
employer, to release me from all obligations and waivers arising from any and all
NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use policies ("BOGUS
AGREEMENTS") that I have entered into with your employer, its partners, licensors,
agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me from any BOGUS AGREEMENTS
on behalf of your employer.
_______________________________________________
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
