Re: [Python-Dev] query: docstring formatting in python distutils code
On 7/7/2010 2:27 PM, Georg Brandl wrote: Am 07.07.2010 19:53, schrieb Éric Araujo: I promised to write a PEP about that some time in the future. (Probably after 3.2 final.) It seems that projects putting Sphinxy reST in their doc are using automatic doc generation. This is however not always the best way to make good doc, as demonstrated by Python’s hand-written, very-high-quality documentation. I know, and this is what I originally intended for Sphinx. However, the calls for automatic doc generation are very loud, and it's understandable that most project can't afford writing their documentation twice. Neither can CPython, really, as evidenced by numerous examples that have shone up on the tracker. Let me add another one. A week ago, Eli Benderdky asked me for help adding missing pieces to the trace module doc. The result so far is http://bugs.python.org/issue9264 After getting that far, I noticed that there were already doc strings for some things that were not documented in the manual, which we added. I also noticed the the public methods already in the manual had not help strings, and hence no helpful help() output. In other words, the manual entries and doc strings were close to disjoint sets. Even when they do overlap as they should, violation of DRY is a maintenance nightmare when anything changes. It would be better if the manual could, to some extent, be docstrings plus additions. -- Terry Jan Reedy ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 16.07.2010 22:55, schrieb Terry Reedy: On 7/7/2010 2:27 PM, Georg Brandl wrote: Am 07.07.2010 19:53, schrieb Éric Araujo: I promised to write a PEP about that some time in the future. (Probably after 3.2 final.) It seems that projects putting Sphinxy reST in their doc are using automatic doc generation. This is however not always the best way to make good doc, as demonstrated by Python’s hand-written, very-high-quality documentation. I know, and this is what I originally intended for Sphinx. However, the calls for automatic doc generation are very loud, and it's understandable that most project can't afford writing their documentation twice. Neither can CPython, really, as evidenced by numerous examples that have shone up on the tracker. Let me add another one. A week ago, Eli Benderdky asked me for help adding missing pieces to the trace module doc. The result so far is http://bugs.python.org/issue9264 After getting that far, I noticed that there were already doc strings for some things that were not documented in the manual, which we added. I also noticed the the public methods already in the manual had not help strings, and hence no helpful help() output. In other words, the manual entries and doc strings were close to disjoint sets. And that's a pity -- very commendable that you work on this. But this is a single case, and most of our library is very well covered by the docs and docstrings. Additions (which usually are small amendments) are made only in the docs, not the docstring, as it should be given the nature of our docstrings. Added functionality is usually documented first in docstrings, which then get copied into the docs, and are padded from there. Even when they do overlap as they should, violation of DRY is a maintenance nightmare when anything changes. It would be better if the manual could, to some extent, be docstrings plus additions. That sounds nice in theory, but opens another can of worms: what belongs in the docstring, what in the addition? How does it work for builtin types, for language features, and so on. Also, the problems I already outlined in my answer to Fred remain... Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On 07/07/2010 12:30 PM, Georg Brandl wrote: Am 07.07.2010 18:09, schrieb Michael Foord: 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. I also agree that interactive help should be the most important factor when writing doc strings for the standard library. Are there any plans to change how pydoc's GUI mode works? Could it use a minimal set of reST to improve it's display? The patch I submitted (*which is waiting to be reviewed) extends the GUI mode so it can show the same info that is available from the help() function. http://bugs.python.org/issue2001 I think the only issues with this patch are what new functions and classes should be part of the public api. * BTW... The bug trackers main links to items with patches, and needing review, doesn't pick up feature requests. Ron ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 09.07.2010 00:01, schrieb Fred Drake: On Thu, Jul 8, 2010 at 5:42 PM, Alexander Belopolsky alexander.belopol...@gmail.com wrote: I am against mark-up in doc-strings, but this problem can be easily solved by placing a magic character at __doc__[0] to indicate that the rest is (mini)reST. Ugh. :) Or __docformat__ can be set appropriately. See: http://www.python.org/dev/peps/pep-0258/#id42 Yes, but[tm] it is not always easy to find the correct module to look for __docformat__ when given an object. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Georg Brandl g.bra...@gmx.net writes: Am 08.07.2010 17:44, schrieb Martin Geisler: Steve Holden st...@holdenweb.com writes: Martin Geisler wrote: Stephen J. Turnbull step...@xemacs.org writes: Just ask Martin, there are too many possibilities here to worry about. If maybe we want it, and he is willing to contribute the parts he wrote to Python under Python's license, then we can worry about whether we really want it and about how much any required hoop-jumping will cost. I would be happy to relicense it under the Python license. I believe the ideal outcome, if it is possible, is for you to sign a contributor agreement. This will license your material to the PSF in such a way that we can release it under whatever license we deem necessary. Sure, I'll be happy to sign a contributor agreement if you guys think it worthwhile to use my little parser and formatter. Problem is, in the case of help() we have no way of knowing whether the given __doc__ string is supposed to be (mini)reST. Of course, reverting to showing the plain content on parsing errors is one possibility, but I can still imagine instances where something is successfully interpreted as reST, but intended to be read and understood verbatim by the author. The minirst module is actually designed to never fail: the text is first divided into paragraphs, and the paragraphs are then looked at one by one to see if they look like something more specific like a list. It's different for Hg, of course, there you can just decide that help texts have to be reST. Right, good point. At first I figured that you could also just convert the docstrings in Python, but since the help builtin is used on lots of code outside of Python this isn't really enough. -- Martin Geisler aragost Trifork -- Professional Mercurial support http://aragost.com/mercurial/ ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Fri, Jul 9, 2010 at 2:51 AM, Georg Brandl g.bra...@gmx.net wrote: Yes, but[tm] it is not always easy to find the correct module to look for __docformat__ when given an object. True. That PEP was written before decorators were common, in particular. That's changed the landscape in substantial ways. It may be that at this point, there's no good way to deal with formatting in docstrings at anything other than the project level, where policies for the code can be set if desired. Ideally, the format of a docstring would be captured along with the docstring itself. -Fred -- Fred L. Drake, Jr.fdrake at gmail.com A storm broke loose in my mind. --Albert Einstein ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Jul 07, 2010, at 12:50 PM, Brett Cannon wrote: On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou solip...@pitrou.net wrote: On Wed, 7 Jul 2010 14:12:17 -0400 Barry Warsaw ba...@python.org wrote: On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. It really looks ugly (and annoying to decipher) when viewed in plain text. I agree. And it is highly repetitive since the signature information is right there already. All of that info in those annotations can easily be written in paragraph form if needed and honestly would read better to my eyes. I actually find it easier to glean the signature details from a regularized docstring than from prose. Especially for autogenerated API documentation, the formal specification lends a consistency to the output that prose doesn't often provide. IME, there isn't much (unnecessary) repeating yourself. Either way, we need to be diligent in accurately describing the signature and semantics of our APIs. -Barry signature.asc Description: PGP signature ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Fri, Jul 9, 2010 at 06:28, Barry Warsaw ba...@python.org wrote: On Jul 07, 2010, at 12:50 PM, Brett Cannon wrote: On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou solip...@pitrou.net wrote: On Wed, 7 Jul 2010 14:12:17 -0400 Barry Warsaw ba...@python.org wrote: On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. It really looks ugly (and annoying to decipher) when viewed in plain text. I agree. And it is highly repetitive since the signature information is right there already. All of that info in those annotations can easily be written in paragraph form if needed and honestly would read better to my eyes. I actually find it easier to glean the signature details from a regularized docstring than from prose. Especially for autogenerated API documentation, the formal specification lends a consistency to the output that prose doesn't often provide. IME, there isn't much (unnecessary) repeating yourself. The key point there is autogenerated API documentation, which Python does not do. Either way, we need to be diligent in accurately describing the signature and semantics of our APIs. Of course. I think this is going to be something our crazy FLUFL likes but the kids don't. =) -Brett -Barry ___ 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/brett%40python.org ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Jul 09, 2010, at 11:55 AM, Brett Cannon wrote: I think this is going to be something our crazy FLUFL likes but the kids don't. =) Don't worry. If you're lucky, you'll get old too. Your eyes will go bad and your mind will think more about tapioca. By then you might even remember that the FLUFL was right after all. :) -Barry signature.asc Description: PGP signature ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Stephen J. Turnbull step...@xemacs.org writes: Benjamin Peterson writes: 2010/7/7 Stephen J. Turnbull step...@xemacs.org: Antoine Pitrou writes: http://selenic.com/hg/file/tip/mercurial/minirst.py Given that Mercurial is GPL, this is probably of no use to us, unfortunately. I must admit that reading this felt strange somehow... that a piece of open source code should be useless. But I understand what you mean :) Given that Martin apparently is the only or main author, I don't see a problem as long as he's willing. And he hasn't assigned the copyright away. (Or that the assignment has an automatic author-use-ok clause like the standard FSF assignment does, etc.) We don't assign copyright in Mercurial, so this should be no problem. This also meant that we had to contact about 300 guys when changing from GPLv2 to GPLv2+. Just ask Martin, there are too many possibilities here to worry about. If maybe we want it, and he is willing to contribute the parts he wrote to Python under Python's license, then we can worry about whether we really want it and about how much any required hoop-jumping will cost. I would be happy to relicense it under the Python license. -- Martin Geisler aragost Trifork: Professional Mercurial support http://aragost.com/mercurial/ ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Martin Geisler wrote: Stephen J. Turnbull step...@xemacs.org writes: Benjamin Peterson writes: 2010/7/7 Stephen J. Turnbull step...@xemacs.org: Antoine Pitrou writes: http://selenic.com/hg/file/tip/mercurial/minirst.py Given that Mercurial is GPL, this is probably of no use to us, unfortunately. I must admit that reading this felt strange somehow... that a piece of open source code should be useless. But I understand what you mean :) Given that Martin apparently is the only or main author, I don't see a problem as long as he's willing. And he hasn't assigned the copyright away. (Or that the assignment has an automatic author-use-ok clause like the standard FSF assignment does, etc.) We don't assign copyright in Mercurial, so this should be no problem. This also meant that we had to contact about 300 guys when changing from GPLv2 to GPLv2+. Just ask Martin, there are too many possibilities here to worry about. If maybe we want it, and he is willing to contribute the parts he wrote to Python under Python's license, then we can worry about whether we really want it and about how much any required hoop-jumping will cost. I would be happy to relicense it under the Python license. I believe the ideal outcome, if it is possible, is for you to sign a contributor agreement. This will license your material to the PSF in such a way that we can release it under whatever license we deem necessary. regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 DjangoCon US September 7-9, 2010http://djangocon.us/ See Python Video! http://python.mirocommunity.org/ Holden Web LLC http://www.holdenweb.com/ ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Steve Holden st...@holdenweb.com writes: Martin Geisler wrote: Stephen J. Turnbull step...@xemacs.org writes: Just ask Martin, there are too many possibilities here to worry about. If maybe we want it, and he is willing to contribute the parts he wrote to Python under Python's license, then we can worry about whether we really want it and about how much any required hoop-jumping will cost. I would be happy to relicense it under the Python license. I believe the ideal outcome, if it is possible, is for you to sign a contributor agreement. This will license your material to the PSF in such a way that we can release it under whatever license we deem necessary. Sure, I'll be happy to sign a contributor agreement if you guys think it worthwhile to use my little parser and formatter. -- Martin Geisler aragost Trifork -- Professional Mercurial support http://aragost.com/mercurial/ ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 08.07.2010 17:44, schrieb Martin Geisler: Steve Holden st...@holdenweb.com writes: Martin Geisler wrote: Stephen J. Turnbull step...@xemacs.org writes: Just ask Martin, there are too many possibilities here to worry about. If maybe we want it, and he is willing to contribute the parts he wrote to Python under Python's license, then we can worry about whether we really want it and about how much any required hoop-jumping will cost. I would be happy to relicense it under the Python license. I believe the ideal outcome, if it is possible, is for you to sign a contributor agreement. This will license your material to the PSF in such a way that we can release it under whatever license we deem necessary. Sure, I'll be happy to sign a contributor agreement if you guys think it worthwhile to use my little parser and formatter. Problem is, in the case of help() we have no way of knowing whether the given __doc__ string is supposed to be (mini)reST. Of course, reverting to showing the plain content on parsing errors is one possibility, but I can still imagine instances where something is successfully interpreted as reST, but intended to be read and understood verbatim by the author. It's different for Hg, of course, there you can just decide that help texts have to be reST. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Thu, Jul 8, 2010 at 5:21 PM, Georg Brandl g.bra...@gmx.net wrote: Problem is, in the case of help() we have no way of knowing whether the given __doc__ string is supposed to be (mini)reST. Of course, reverting to showing the plain content on parsing errors is one possibility, but I can still imagine instances where something is successfully interpreted as reST, but intended to be read and understood verbatim by the author. The docstring processing PEP provides for this: http://www.python.org/dev/peps/pep-0258/#id42 -Fred -- Fred L. Drake, Jr.fdrake at gmail.com A storm broke loose in my mind. --Albert Einstein ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Thu, Jul 8, 2010 at 5:21 PM, Georg Brandl g.bra...@gmx.net wrote: .. Problem is, in the case of help() we have no way of knowing whether the given __doc__ string is supposed to be (mini)reST. I am against mark-up in doc-strings, but this problem can be easily solved by placing a magic character at __doc__[0] to indicate that the rest is (mini)reST. The magic character should be chosen to be inconspicuous and unlikely to appear at the start of a plain-text docstting. For example, any type closing braces, ), }. ] will do, or any end of sentence punctuation such as . or !. ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Thu, Jul 8, 2010 at 5:42 PM, Alexander Belopolsky alexander.belopol...@gmail.com wrote: I am against mark-up in doc-strings, but this problem can be easily solved by placing a magic character at __doc__[0] to indicate that the rest is (mini)reST. Or __docformat__ can be set appropriately. See: http://www.python.org/dev/peps/pep-0258/#id42 -Fred -- Fred L. Drake, Jr.fdrake at gmail.com A storm broke loose in my mind. --Albert Einstein ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Fred Drake wrote: On Thu, Jul 8, 2010 at 5:42 PM, Alexander Belopolsky alexander.belopol...@gmail.com wrote: I am against mark-up in doc-strings, but this problem can be easily solved by placing a magic character at __doc__[0] to indicate that the rest is (mini)reST. Or __docformat__ can be set appropriately. See: http://www.python.org/dev/peps/pep-0258/#id42 That is _so_ Python 2 ;-) regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 DjangoCon US September 7-9, 2010http://djangocon.us/ See Python Video! http://python.mirocommunity.org/ Holden Web LLC http://www.holdenweb.com/ ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Steve Holden writes: That is _so_ Python 2 ;-) High praise! ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
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 ? 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-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 07, 2010 at 09:36:10PM +0530, 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 ? I don't understand... Frist, you can already use help(os.getcwd) to get the same result. Second, what would we be breaking? We'd be making the straight text representation a bit more cluttered in return for adding certain kinds of meta-information into the markup. I think it's a judgement call... cheers, --titus -- C. Titus Brown, 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/archive%40mail-archive.com
Re: [Python-Dev] query: docstring formatting in python distutils code
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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 07, 2010 at 05:09:40PM +0100, Michael Foord 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 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. OK. I guess docutils isn't in the stdlib (should it be?) or else we could modify 'help' to use it to prepare a straight text formatting. cheers, --titus -- C. Titus Brown, 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/archive%40mail-archive.com
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 9:39 PM, Michael Foord fuzzy...@voidspace.org.ukwrote: 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
Re: [Python-Dev] query: docstring formatting in python distutils code
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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 11:00 PM, Georg Brandl g.bra...@gmx.net wrote: 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. What are the specific advantages that you see? Can it more useful in some cases than the other? -- Senthil ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
I promised to write a PEP about that some time in the future. (Probably after 3.2 final.) Nice. It seems that projects putting Sphinxy reST in their doc are using automatic doc generation. This is however not always the best way to make good doc, as demonstrated by Python’s hand-written, very-high-quality documentation. 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. Clear answer, thanks! We have backported some modules in distutils2, and some docstrings already contain Sphinxy reST (e.g. :param: and :pep:), it’s good to know now that we shouldn’t put hours into that to see it reverted later. Regards ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. def create_foo(name, parent=None): Create the named foo. The named foo must not already exist, but if optional `parent` is given, it must exist. :param name: The name of the new foo. :type name: string :param parent: The new foo's parent. If given, this must exist. :type parent: string :return: The new foo. :rtype: `Foo` :raises BadFooNameError: when `name` is illegal. :raises FooAlreadyExistsError: when a foo with `name` already exists. :raises BadParentError: when the foo's parent does not exist. We could then generate automatic API docs from this, a la: http://www.blender.org/documentation/248PythonDoc/ -Barry signature.asc Description: PGP signature ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On 7/7/10 1:53 PM, Éric Araujo wrote: I promised to write a PEP about that some time in the future. (Probably after 3.2 final.) Nice. It seems that projects putting Sphinxy reST in their doc are using automatic doc generation. This is however not always the best way to make good doc, as demonstrated by Python’s hand-written, very-high-quality documentation. This is a false dichotomy. Many of those projects using Sphinxy reST in their docstrings are using the semi-automatic[1] doc generation provided by Sphinx to construct *part* of their documentation. Namely, the reference of functions, classes and methods. A large part of Python's library reference consists of exactly this. Having a function's docstring provide the content for its entry in the library reference has the substantial DRY benefit of having exactly one source for the comprehensive documentation of that function available from both help() and the manual. As someone who uses the interactive prompt to play with things and read docstrings intensively, I would really like to see docstrings providing the same information as the manual. Of course, opinions differ about how comprehensive docstrings should be compared to the reference manual's entries. And there are technical reasons for not wanting to try to extract docstrings from code (e.g. platform-specific modules). But one should not fear that the quality of the manual would decline. [1] That's the really nice thing about Sphinx's docstring extraction features in contrast with other such tools. It doesn't generate a manual from the docstrings; it makes you explicitly reference the docstrings into the manual's text. This would fit in very naturally with Python's library reference. -- Robert Kern I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth. -- Umberto Eco ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 07.07.2010 19:53, schrieb Éric Araujo: I promised to write a PEP about that some time in the future. (Probably after 3.2 final.) Nice. It seems that projects putting Sphinxy reST in their doc are using automatic doc generation. This is however not always the best way to make good doc, as demonstrated by Python’s hand-written, very-high-quality documentation. I know, and this is what I originally intended for Sphinx. However, the calls for automatic doc generation are very loud, and it's understandable that most project can't afford writing their documentation twice. 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. Clear answer, thanks! We have backported some modules in distutils2, and some docstrings already contain Sphinxy reST (e.g. :param: and :pep:), it’s good to know now that we shouldn’t put hours into that to see it reverted later. :pep: isn't Sphinxy, put provided by docutils, and the :param foo: field lists are also valid reST, if rendered a bit awkwardly without the transforms that Sphinx does to display them in epydoc style. 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 2:12 PM, Barry Warsaw ba...@python.org wrote: .. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. def create_foo(name, parent=None): Create the named foo. The named foo must not already exist, but if optional `parent` is given, it must exist. :param name: The name of the new foo. :type name: string .. -1. Repeating the function signature in the docstring only adds clutter and Java-style formal types/exceptions specifications are rarely appropriate in Python. I think marking arguments up with * as in *name*, *parent*, should be enough in most cases. ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, 7 Jul 2010 14:12:17 -0400 Barry Warsaw ba...@python.org wrote: On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. It really looks ugly (and annoying to decipher) when viewed in plain text. Regards Antoine. def create_foo(name, parent=None): Create the named foo. The named foo must not already exist, but if optional `parent` is given, it must exist. :param name: The name of the new foo. :type name: string :param parent: The new foo's parent. If given, this must exist. :type parent: string :return: The new foo. :rtype: `Foo` :raises BadFooNameError: when `name` is illegal. :raises FooAlreadyExistsError: when a foo with `name` already exists. :raises BadParentError: when the foo's parent does not exist. We could then generate automatic API docs from this, a la: http://www.blender.org/documentation/248PythonDoc/ -Barry ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 2:27 PM, Georg Brandl g.bra...@gmx.net wrote: I know, and this is what I originally intended for Sphinx. However, the calls for automatic doc generation are very loud, and it's understandable that most project can't afford writing their documentation twice. The ability to provide extended content beyond what's provided in the docstring using the auto* constructs may make it feasible to start avoiding some of those DRY violations for Python's standard library; I'm enjoying those for another project. I hope we don't end up in a position where we can't use the auto* constructs in the Python documentation. -Fred -- Fred L. Drake, Jr.fdrake at gmail.com A storm broke loose in my mind. --Albert Einstein ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou solip...@pitrou.net wrote: On Wed, 7 Jul 2010 14:12:17 -0400 Barry Warsaw ba...@python.org wrote: On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. It really looks ugly (and annoying to decipher) when viewed in plain text. I agree. And it is highly repetitive since the signature information is right there already. All of that info in those annotations can easily be written in paragraph form if needed and honestly would read better to my eyes. -Brett Regards Antoine. def create_foo(name, parent=None): Create the named foo. The named foo must not already exist, but if optional `parent` is given, it must exist. :param name: The name of the new foo. :type name: string :param parent: The new foo's parent. If given, this must exist. :type parent: string :return: The new foo. :rtype: `Foo` :raises BadFooNameError: when `name` is illegal. :raises FooAlreadyExistsError: when a foo with `name` already exists. :raises BadParentError: when the foo's parent does not exist. We could then generate automatic API docs from this, a la: http://www.blender.org/documentation/248PythonDoc/ -Barry ___ 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/brett%40python.org ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 10:30, Georg Brandl g.bra...@gmx.net wrote: 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.) For those of you who aren't aware, there actually already is a PEP on using reST in docstrings: http://python.org/dev/peps/pep-0287/ . But it could stand to be updated by Georg with current practice with our internal doc practices as 2002 was back when we were still using LaTeX. -Brett 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/brett%40python.org ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 07.07.2010 20:12, schrieb Barry Warsaw: On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. def create_foo(name, parent=None): Create the named foo. The named foo must not already exist, but if optional `parent` is given, it must exist. :param name: The name of the new foo. :type name: string :param parent: The new foo's parent. If given, this must exist. :type parent: string :return: The new foo. :rtype: `Foo` :raises BadFooNameError: when `name` is illegal. :raises FooAlreadyExistsError: when a foo with `name` already exists. :raises BadParentError: when the foo's parent does not exist. We could then generate automatic API docs from this, a la: http://www.blender.org/documentation/248PythonDoc/ Yes, but: do we want this? 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
Re: [Python-Dev] query: docstring formatting in python distutils code
C. Titus Brown c...@msu.edu writes: I guess docutils isn't in the stdlib (should it be?) or else we could modify 'help' to use it to prepare a straight text formatting. We're using light-weight ReST markup in the Mercurial help texts and transform it into straight text upon display in the terminal. We want no external dependencies for Mercurial, so I wrote a mini ReST parser in about 400 lines of code. It cheats a lot and can only handle simple constructs... but maybe it would be interesting for Python's help? You find it here: http://selenic.com/hg/file/tip/mercurial/minirst.py Its test and the corresponding output shows the markup it can parse: http://selenic.com/hg/file/tip/tests/test-minirst.py http://selenic.com/hg/file/tip/tests/test-minirst.py.out It would of course be much nicer to have Docutils in the standard library. I'm not a Docutils developer, but to me it seems that Docutils is now a very stable and widely used package, so it would IMHO make sense to include it. -- Martin Geisler Mercurial links: http://mercurial.ch/ pgpf0R31gMZHO.pgp Description: PGP signature ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 07.07.2010 21:11, schrieb Fred Drake: On Wed, Jul 7, 2010 at 2:27 PM, Georg Brandl g.bra...@gmx.net wrote: I know, and this is what I originally intended for Sphinx. However, the calls for automatic doc generation are very loud, and it's understandable that most project can't afford writing their documentation twice. The ability to provide extended content beyond what's provided in the docstring using the auto* constructs may make it feasible to start avoiding some of those DRY violations for Python's standard library; I'm enjoying those for another project. I hope we don't end up in a position where we can't use the auto* constructs in the Python documentation. Let's say we were okay with giving up single-source docs, one potential problem is that autodoc needs to import the modules in question, which can become a problem, on one hand for platform-specific modules, on the other because the Python building the docs is not necessarily the Python that is documented. 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Am 07.07.2010 21:52, schrieb Brett Cannon: On Wed, Jul 7, 2010 at 10:30, Georg Brandl g.bra...@gmx.net wrote: 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.) For those of you who aren't aware, there actually already is a PEP on using reST in docstrings: http://python.org/dev/peps/pep-0287/ . But it could stand to be updated by Georg with current practice with our internal doc practices as 2002 was back when we were still using LaTeX. Thanks for the reference, Brett. I do not intend to do my work in PEP 287 (though it probably could be given a few updates, have to look in detail), but rather refer to it in the new one, since my proposed PEP was less about actual syntax of reST docstrings than about their use in the standard library. As far as I could see, most recommendations from PEP 287 would apply to them. 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, 07 Jul 2010 22:58:47 +0200 Martin Geisler m...@lazybytes.net wrote: C. Titus Brown c...@msu.edu writes: I guess docutils isn't in the stdlib (should it be?) or else we could modify 'help' to use it to prepare a straight text formatting. We're using light-weight ReST markup in the Mercurial help texts and transform it into straight text upon display in the terminal. We want no external dependencies for Mercurial, so I wrote a mini ReST parser in about 400 lines of code. It cheats a lot and can only handle simple constructs... but maybe it would be interesting for Python's help? You find it here: http://selenic.com/hg/file/tip/mercurial/minirst.py Given that Mercurial is GPL, this is probably of no use to us, unfortunately. Regards Antoine. ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
On 07/07/2010 21:54, Georg Brandl wrote: Am 07.07.2010 20:12, schrieb Barry Warsaw: On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote: 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. Does it make sense to add (reST-style) epydoc markup for API signatures? E.g. def create_foo(name, parent=None): Create the named foo. The named foo must not already exist, but if optional `parent` is given, it must exist. :param name: The name of the new foo. :type name: string :param parent: The new foo's parent. If given, this must exist. :type parent: string :return: The new foo. :rtype: `Foo` :raises BadFooNameError: when `name` is illegal. :raises FooAlreadyExistsError: when a foo with `name` already exists. :raises BadParentError: when the foo's parent does not exist. We could then generate automatic API docs from this, a la: http://www.blender.org/documentation/248PythonDoc/ Yes, but: do we want this? -1 :-) I find those epydoc style framed API docs very hard to read and navigate. On the other hand autogenerated API docs *can* be good looking and usable. Michael 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/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
Re: [Python-Dev] query: docstring formatting in python distutils code
On Wed, Jul 7, 2010 at 4:58 PM, Georg Brandl g.bra...@gmx.net wrote: Let's say we were okay with giving up single-source docs, It's not clear that this is a goal. one potential problem is that autodoc needs to import the modules in question, which can become a problem, on one hand for platform-specific modules, on the other because the Python building the docs is not necessarily the Python that is documented. This is an excellent point. I'm less worried about the platform-specific issues, since we can decide that those in particular can't use the auto* support, but the need to build docs for different versions/implementations of Python is an interesting use case. -Fred -- Fred L. Drake, Jr.fdrake at gmail.com A storm broke loose in my mind. --Albert Einstein ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Antoine Pitrou writes: http://selenic.com/hg/file/tip/mercurial/minirst.py Given that Mercurial is GPL, this is probably of no use to us, unfortunately. Given that Martin apparently is the only or main author, I don't see a problem as long as he's willing. Martin? ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
2010/7/7 Stephen J. Turnbull step...@xemacs.org: Antoine Pitrou writes: http://selenic.com/hg/file/tip/mercurial/minirst.py Given that Mercurial is GPL, this is probably of no use to us, unfortunately. Given that Martin apparently is the only or main author, I don't see a problem as long as he's willing. And he hasn't assigned the copyright away. -- Regards, Benjamin ___ 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
Re: [Python-Dev] query: docstring formatting in python distutils code
Benjamin Peterson writes: 2010/7/7 Stephen J. Turnbull step...@xemacs.org: Antoine Pitrou writes: http://selenic.com/hg/file/tip/mercurial/minirst.py Given that Mercurial is GPL, this is probably of no use to us, unfortunately. Given that Martin apparently is the only or main author, I don't see a problem as long as he's willing. And he hasn't assigned the copyright away. (Or that the assignment has an automatic author-use-ok clause like the standard FSF assignment does, etc.) Just ask Martin, there are too many possibilities here to worry about. If maybe we want it, and he is willing to contribute the parts he wrote to Python under Python's license, then we can worry about whether we really want it and about how much any required hoop-jumping will cost. ___ 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
