<br><br><div class="gmail_quote">On Wed, Jul 7, 2010 at 9:39 PM, Michael Foord <span dir="ltr"><<a href="mailto:fuzzyman@voidspace.org.uk">fuzzyman@voidspace.org.uk</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div bgcolor="#ffffff" text="#000000"><div class="im">
On 07/07/2010 17:06, Shashwat Anand wrote:
<blockquote type="cite"><br>
<br>
<div class="gmail_quote">On Wed, Jul 7, 2010 at 9:24 PM, C. Titus
Brown <span dir="ltr"><<a href="mailto:ctb@msu.edu" target="_blank">ctb@msu.edu</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left:1px solid rgb(204, 204, 204);margin:0pt 0pt 0pt 0.8ex;padding-left:1ex">Hi
all,<br>
<br>
over on the fellowship o' the packaging mailing list, one of our GSoC
students<br>
(merwok) asked about how much formatting info should go into Python
stdlib<br>
docstrings. Right now the stdlib docstrings are primarily text, AFAIK;
but<br>
with the switch to Sphinx for the official Python docs, should we permit<br>
ReST-general and/or Sphinx-specific markup in docstrings?<br>
<br>
Hmm, I don't actually see that the stdlib docstrings are imported into
the<br>
Python documentation anywhere, so maybe the use of Sphinx isn't that<br>
relevant. But how about ReST in general?<br>
</blockquote>
<div><br>
</div>
<div>So will we be able to use .__docs__ within python interpretor,
which is quite handy feature.</div>
<div>>>> print(os.getcwd.__doc__)</div>
<div>getcwd() -> path</div>
<div><br>
</div>
<div>Return a string representing the current working directory.</div>
<div>Also some python interpretors like bpython uses it ; a snapshot
here - h<a>ttp://cl.ly/c5bb3be4a01d9d44732f</a></div>
<div>So will it be ok to break them ?</div>
</div>
</blockquote>
<br></div>
Using ReST won't *break* these tools, but may make the output less
readable. <br></div></blockquote><div><br></div><div>Oops. Sorry for the wrong choice of word. I meant the 'output will be less readable', text are perhaps easier to read than ReST, thats what I meant. </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div bgcolor="#ffffff" text="#000000">
<br>
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.<br>
<br>
Michael<br>
<br>
<blockquote type="cite"><div class="im">
<div class="gmail_quote">
<div> </div>
<blockquote class="gmail_quote" style="border-left:1px solid rgb(204, 204, 204);margin:0pt 0pt 0pt 0.8ex;padding-left:1ex"><br>
See<br>
<br>
<a href="http://sphinx.pocoo.org/markup/index.html" target="_blank">http://sphinx.pocoo.org/markup/index.html</a><br>
<br>
for sphinx-specific markup constructs.<br>
<br>
thanks,<br>
--titus<br>
<font color="#888888">--<br>
C. Titus Brown, <a href="mailto:ctb@msu.edu" target="_blank">ctb@msu.edu</a><br>
<br>
</font></blockquote>
</div>
<br>
</div><pre><fieldset></fieldset>
_______________________________________________
Python-Dev mailing list
<div class="im"><a href="mailto:Python-Dev@python.org" target="_blank">Python-Dev@python.org</a>
<a href="http://mail.python.org/mailman/listinfo/python-dev" target="_blank">http://mail.python.org/mailman/listinfo/python-dev</a></div>
Unsubscribe: <a href="http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk" target="_blank">http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk</a>
</pre>
</blockquote>
<br>
<br>
<pre cols="72">--
<a href="http://www.ironpythoninaction.com/" target="_blank">http://www.ironpythoninaction.com/</a>
<a href="http://www.voidspace.org.uk/blog" target="_blank">http://www.voidspace.org.uk/blog</a>
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.
</pre>
</div>
</blockquote></div><br>