On Wed, Jul 7, 2010 at 9:39 PM, Michael Foord wrote:
> On 07/07/2010 17:06, Shashwat Anand wrote:
>
>
>
> On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown 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 - h
> ttp://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.
>
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.
>
> 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
>>
>>
>
> ___
> Python-Dev mailing list
> python-...@python.orghttp://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
