On Wed, Jul 7, 2010 at 9:39 PM, Michael Foord <fuzzy...@voidspace.org.uk>wrote:
> On 07/07/2010 17:06, Shashwat Anand wrote: > > > > On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown <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 - 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
