From barry at python.org Tue Apr 13 23:12:19 2010 From: barry at python.org (Barry Warsaw) Date: Tue, 13 Apr 2010 17:12:19 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings Message-ID: <20100413171219.7a2c10a2@heresy> Hello Doc-Siggers, During some recent work on the PEP 3147, I had a need to add some documentation (docstrings) to some new functions. To document the function arguments I added epydoc reST style markup: def ensure_bytecode_path(bytecode_path): """Ensure that the __pycache__ directory for PEP 3147 pyc file exists. :param bytecode_path: File system path to PEP 3147 pyc file. """ Now, I didn't even think twice about this because several of the larger Python projects I work on have already adopted epydoc reST markup for API. During his review, Antoine disapproved of this, pointing to PEPs 257 and 287. My reading of these PEPs however, certainly doesn't prohibit the use of epydoc reST markup. Georg and I pointed to the lack of a clear, consistent convention in the Python stdlib. I would like to propose that epydoc reST markup be made that convention. http://epydoc.sourceforge.net/epydoc.html#epydoc-fields PEP 257 does include an example for keyword arguments, but not much more is said about them. epydoc reST markup is compliant with PEP 287 IMO, by adopting reST syntax. I think Sphinx does a pretty good job of handling such API markup too. A PEP might be necessary to make this a firm decision. What do you think about adopting epydoc reST markup for documenting the stdlib API? -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From janssen at parc.com Tue Apr 13 23:56:42 2010 From: janssen at parc.com (Bill Janssen) Date: Tue, 13 Apr 2010 14:56:42 PDT Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100413171219.7a2c10a2@heresy> References: <20100413171219.7a2c10a2@heresy> Message-ID: <27924.1271195802@parc.com> Good with me, but... Is epydoc still being maintained? The last release was over two years ago, and the current release (3.0) doesn't work with the current docutils (0.6). https://sourceforge.net/tracker/?func=detail&aid=2895197&group_id=32455&atid=405618 Bill From fuzzyman at voidspace.org.uk Wed Apr 14 00:24:13 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 00:24:13 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <27924.1271195802@parc.com> References: <20100413171219.7a2c10a2@heresy> <27924.1271195802@parc.com> Message-ID: <4BC4EF0D.6020502@voidspace.org.uk> On 13/04/2010 23:56, Bill Janssen wrote: > Good with me, but... > > Is epydoc still being maintained? The last release was over two years > ago, and the current release (3.0) doesn't work with the current > docutils (0.6). > I don't think that is particularly relevant to the proposal. The proposal is that we adopt a standard, once we have done that other tools can be built that use it. Epydoc maybe essentially dead but it doesn't affect the quality (or otherwise) of the docstring standard. Michael > https://sourceforge.net/tracker/?func=detail&aid=2895197&group_id=32455&atid=405618 > > Bill > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ From g.brandl at gmx.net Wed Apr 14 01:25:48 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Tue, 13 Apr 2010 23:25:48 +0000 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100413171219.7a2c10a2@heresy> References: <20100413171219.7a2c10a2@heresy> Message-ID: Am 13.04.2010 21:12, schrieb Barry Warsaw: > Hello Doc-Siggers, > > During some recent work on the PEP 3147, I had a need to add some > documentation (docstrings) to some new functions. To document the function > arguments I added epydoc reST style markup: > > def ensure_bytecode_path(bytecode_path): > """Ensure that the __pycache__ directory for PEP 3147 pyc file exists. > > :param bytecode_path: File system path to PEP 3147 pyc file. > """ > > Now, I didn't even think twice about this because several of the larger Python > projects I work on have already adopted epydoc reST markup for API. During > his review, Antoine disapproved of this, pointing to PEPs 257 and 287. My > reading of these PEPs however, certainly doesn't prohibit the use of epydoc > reST markup. Georg and I pointed to the lack of a clear, consistent convention > in the Python stdlib. I would like to propose that epydoc reST markup be made > that convention. > > http://epydoc.sourceforge.net/epydoc.html#epydoc-fields So far, so good, but I would *not* want to make a ":param foo:" section a recommendation or even mandatory. (IMO it's too verbose, parameters can be explained in the text just fine.) Valid reST is a first goal, and it should be achievable to slowly convert docstrings to that. > PEP 257 does include an example for keyword arguments, but not much more is > said about them. epydoc reST markup is compliant with PEP 287 IMO, by > adopting reST syntax. I think Sphinx does a pretty good job of handling such > API markup too. Yes, I've tried to be compatible to what Epydoc supports. > A PEP might be necessary to make this a firm decision. What do you think > about adopting epydoc reST markup for documenting the stdlib API? >From me, +1. (Also for this reason: Many projects pull docstrings into their Sphinx docs via autodoc these days, and some also document inherited APIs. When these inherited APIs come from the stdlib, the markup is often confusing or not even valid reST.) Georg From fuzzyman at voidspace.org.uk Wed Apr 14 01:30:19 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 01:30:19 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> Message-ID: <4BC4FE8B.6020604@voidspace.org.uk> On 14/04/2010 01:25, Georg Brandl wrote: > [snip...] >> A PEP might be necessary to make this a firm decision. What do you think >> about adopting epydoc reST markup for documenting the stdlib API? >> > > From me, +1. > > (Also for this reason: Many projects pull docstrings into their Sphinx docs > via autodoc these days, and some also document inherited APIs. When these > inherited APIs come from the stdlib, the markup is often confusing or not > even valid reST.) > Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for parameters (etc) well enough to have an opinion on that. Michael Foord > Georg > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ From ralf.gommers at googlemail.com Wed Apr 14 02:26:25 2010 From: ralf.gommers at googlemail.com (Ralf Gommers) Date: Wed, 14 Apr 2010 08:26:25 +0800 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC4FE8B.6020604@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord wrote: > On 14/04/2010 01:25, Georg Brandl wrote: > >> [snip...] >> >> A PEP might be necessary to make this a firm decision. What do you think >>> about adopting epydoc reST markup for documenting the stdlib API? >>> >>> >> > From me, +1. >> >> (Also for this reason: Many projects pull docstrings into their Sphinx >> docs >> via autodoc these days, and some also document inherited APIs. When these >> inherited APIs come from the stdlib, the markup is often confusing or not >> even valid reST.) >> >> > > Definite +1 from me on adopting reST in docstrings as a standard. I haven't > looked at the Epydoc convention for parameters (etc) well enough to have an > opinion on that. > > Agreed that a reST based standard would be very useful. One point that is important to me (and many scientific users) is how the docstring looks in a terminal. Numpy has been developing a standard for docstrings and writing docs that both looks good in plain text and in docs rendered with Sphinx. http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This is quickly becoming a standard for scientific projects (numpy, scipy, matplotlib, ipython etc). For an example see http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/, click "source" for plain text version. Basic format is: """Summary line. Parameters ------------ param1 : int Description of param1. Can be multi-line. param2: array Description of param2. Returns ------- val1 : float Example ------- """ There is also a very nice wiki doc editor with svn merging support (into the wiki automatic, patch generation for import into svn) here: http://docs.scipy.org/numpy/docs/. As far as I can tell the epydoc standard is not nearly as readable as the numpy standard in plain text, so please consider the latter or something similar for adoption. Best regards, Ralf -------------- next part -------------- An HTML attachment was scrubbed... URL: From barry at python.org Wed Apr 14 02:39:19 2010 From: barry at python.org (Barry Warsaw) Date: Tue, 13 Apr 2010 20:39:19 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> Message-ID: <20100413203919.125da905@heresy> On Apr 13, 2010, at 11:25 PM, Georg Brandl wrote: >So far, so good, but I would *not* want to make a ":param foo:" section >a recommendation or even mandatory. (IMO it's too verbose, parameters can be >explained in the text just fine.) Valid reST is a first goal, and it should >be achievable to slowly convert docstrings to that. I actually find prose descriptions of parameters and return values much harder to read. YMMV of course. We can definitely agree on valid reST being the top priority, as PEP 287 states. Even this of course is not mandatory (yet). I think it is useful to be more prescriptive, such that if folks want to markup their parameters in other than prose, epydoc reST style is the officially preferred format to use. That way, we can begin to standardize the stdlib, and build and extend tools that read that format. >> PEP 257 does include an example for keyword arguments, but not much more is >> said about them. epydoc reST markup is compliant with PEP 287 IMO, by >> adopting reST syntax. I think Sphinx does a pretty good job of handling such >> API markup too. > >Yes, I've tried to be compatible to what Epydoc supports. Excellent. >> A PEP might be necessary to make this a firm decision. What do you think >> about adopting epydoc reST markup for documenting the stdlib API? > >>From me, +1. > >(Also for this reason: Many projects pull docstrings into their Sphinx docs >via autodoc these days, and some also document inherited APIs. When these >inherited APIs come from the stdlib, the markup is often confusing or not >even valid reST.) Yep. I'd love to see guidelines and stronger recommendations that people can follow so that over time, we fix this. Thanks, -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From barry at python.org Wed Apr 14 02:40:47 2010 From: barry at python.org (Barry Warsaw) Date: Tue, 13 Apr 2010 20:40:47 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC4FE8B.6020604@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> Message-ID: <20100413204047.4502b11e@heresy> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >Definite +1 from me on adopting reST in docstrings as a standard. I >haven't looked at the Epydoc convention for parameters (etc) well enough >to have an opinion on that. The thing I like about them is that the rules are very simple, and once learned are easy to remember. -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From goodger at python.org Wed Apr 14 02:55:53 2010 From: goodger at python.org (David Goodger) Date: Tue, 13 Apr 2010 20:55:53 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100413171219.7a2c10a2@heresy> References: <20100413171219.7a2c10a2@heresy> Message-ID: On Tue, Apr 13, 2010 at 17:12, Barry Warsaw wrote: > During some recent work on the PEP 3147, I had a need to add some > documentation (docstrings) to some new functions. ?To document the function > arguments I added epydoc reST style markup: > > def ensure_bytecode_path(bytecode_path): > ? ?"""Ensure that the __pycache__ directory for PEP 3147 pyc file exists. > > ? ?:param bytecode_path: File system path to PEP 3147 pyc file. > ? ?""" > > Now, I didn't even think twice about this because several of the larger Python > projects I work on have already adopted epydoc reST markup for API. ?During > his review, Antoine disapproved of this, pointing to PEPs 257 and 287. ?My > reading of these PEPs however, certainly doesn't prohibit the use of epydoc > reST markup. PEP 257 doesn't address docstring syntax at all, just conventions. PEP 287 addresses "only the low-level syntax of docstrings". IOW, these PEPs don't apply to Antoine's concern. High-level semantics simply aren't addressed by them. (As the author or co-author, I should know :-) I once wrote up some notes about docstring semantics: http://docutils.sourceforge.net/docs/dev/semantics.html >?Georg and I pointed to the lack of a clear, consistent convention > in the Python stdlib. ?I would like to propose that epydoc reST markup be made > that convention. > > http://epydoc.sourceforge.net/epydoc.html#epydoc-fields I'm not a fan of epydoc's conventions (too much like JavaDoc, too verbose, too strict). On the other hand, "now is better than never" -- working code and rough consensus rule. I wouldn't object to making the epydoc field conventions *a* standard convention, allowing for others. Just as choice of markup is very much a matter of personal preference (some people *love* dealing with XML directly), choice of API documentation semantics is also a personal preference thing. We would be wise to allow for choice. -- David Goodger From barry at python.org Wed Apr 14 13:38:45 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 07:38:45 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> Message-ID: <20100414073845.479aa15d@heresy> On Apr 13, 2010, at 08:55 PM, David Goodger wrote: >I'm not a fan of epydoc's conventions (too much like JavaDoc, too >verbose, too strict). On the other hand, "now is better than never" -- >working code and rough consensus rule. I wouldn't object to making the >epydoc field conventions *a* standard convention, allowing for others. > >Just as choice of markup is very much a matter of personal preference >(some people *love* dealing with XML directly), choice of API >documentation semantics is also a personal preference thing. We would >be wise to allow for choice. Perhaps it would be useful to survey some popular and/or large Python code bases to see what is currently being used? That would be a good start to try to figure out what the stdlib should recommend. I do think that we should make strong recommendations for the standard library, so that we have consistency and good online documentation. I personally like epydoc reST format (not JavaDoc) but I'm sure there are other decent formats. -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From fuzzyman at voidspace.org.uk Wed Apr 14 14:44:03 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 14:44:03 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414073845.479aa15d@heresy> References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> Message-ID: <4BC5B893.1050702@voidspace.org.uk> On 14/04/2010 13:38, Barry Warsaw wrote: > On Apr 13, 2010, at 08:55 PM, David Goodger wrote: > > >> I'm not a fan of epydoc's conventions (too much like JavaDoc, too >> verbose, too strict). On the other hand, "now is better than never" -- >> working code and rough consensus rule. I wouldn't object to making the >> epydoc field conventions *a* standard convention, allowing for others. >> >> Just as choice of markup is very much a matter of personal preference >> (some people *love* dealing with XML directly), choice of API >> documentation semantics is also a personal preference thing. We would >> be wise to allow for choice. >> > Perhaps it would be useful to survey some popular and/or large Python code > bases to see what is currently being used? That would be a good start to try > to figure out what the stdlib should recommend. > > I do think that we should make strong recommendations for the standard > library, so that we have consistency and good online documentation. I > personally like epydoc reST format (not JavaDoc) but I'm sure there are other > decent formats. > I'm not aware of other formats beyond epydoc and javadoc (I agree with your opinion on javadoc) - oh and the .NET xml format which I strongly recommend we steer clear of. Do you have any references? I don't recall *ever* seeing a consistent pattern for specifying parameters and return values in Python docstrings. I too would prefer a consistent pattern be adopted for the Python standard library. Good luck finding someone to go and change all the docstrings in the standard library to use it... Michael > -Barry > > > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From barry at python.org Wed Apr 14 14:10:58 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 08:10:58 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5B893.1050702@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> Message-ID: <20100414081058.29868be4@heresy> On Apr 14, 2010, at 02:44 PM, Michael Foord wrote: >I'm not aware of other formats beyond epydoc and javadoc (I agree with >your opinion on javadoc) - oh and the .NET xml format which I strongly >recommend we steer clear of. Do you have any references? XML is not human readable or writable (IMNSHO :). As far as epydoc, this is probably the only page you care about: http://epydoc.sourceforge.net/manual-fields.html It describes the fields that are used to describe parameters, return types, and exceptions. Note that while the body of that page uses "Epytext" format, the table near the top of the page shows the three alternative syntaxes. Of those of course I recommend reST (the middle column). You have to mentally translate the syntax in the body of the page to reST though. Keep in mind too that it's not always necessary to include *every* field in a function's docstring. Obviously, include only what is useful to the consumer of the function's documentation. For example, when it's completely obvious, or when I actually don't know (e.g. because the method proxies some other method 3 levels deep), I might not include the :type: field. I also won't include obvious, common exceptions. I do think *that* can be left to the author's taste. Here's an example: def inject_message(mlist, msg, recips=None, switchboard=None, **kws): """Inject a message into a queue. :param mlist: The mailing list this message is destined for. :type mlist: `IMailingList` :param msg: The message object to inject. :type msg: `email.message.Message` or derived :param recips: Optional set of recipients to put into the message's metadata. :type recips: sequence of strings :param switchboard: Optional name of switchboard to inject this message into. If not given, the 'in' switchboard is used. :type switchboard: string :param kws: Additional values for the message metadata. :type kws: dictionary """ Note that :param: values are complete sentences, while :type: values are informative types, not necessarily explicit types (e.g. an interface for mlist and 'string' instead of 'str' or 'unicode' for switchboard). This function doesn't return anything and doesn't explicitly raise any exceptions. The implicit KeyErrors that could be raised are not described. >I don't recall *ever* seeing a consistent pattern for specifying >parameters and return values in Python docstrings. Exactly. :) >I too would prefer a consistent pattern be adopted for the Python >standard library. Good luck finding someone to go and change all the >docstrings in the standard library to use it... Like all other coding standards we have for the stdlib, the migration can happen opportunistically over time. But folks need a target or nothing will ever happen. -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From fdrake at acm.org Wed Apr 14 15:08:43 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 09:08:43 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5B893.1050702@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord wrote: > I too would prefer a consistent pattern be adopted for the Python standard > library. Good luck finding someone to go and change all the docstrings in > the standard library to use it... We found someone interested in converting the LaTeX to ReST, didn't we? :-) If we can come up with a good recommendation, it'll take hold fairly thoroughly. Not quickly at first, but once there's value (tools) to be had it'll happen. The value for the standard library is that the documentation maintenance can be moved closer to the code, and is less likely to get out of sync. -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller From ncoghlan at gmail.com Wed Apr 14 15:58:43 2010 From: ncoghlan at gmail.com (Nick Coghlan) Date: Wed, 14 Apr 2010 23:58:43 +1000 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100413204047.4502b11e@heresy> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> Message-ID: <4BC5CA13.7020904@gmail.com> Barry Warsaw wrote: > On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: > >> Definite +1 from me on adopting reST in docstrings as a standard. I >> haven't looked at the Epydoc convention for parameters (etc) well enough >> to have an opinion on that. > > The thing I like about them is that the rules are very simple, and once > learned are easy to remember. Did you look at the NumPy guidelines Ralf posted?: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines Those look very clean to me, and fairly similar to what we already do in the ReST docs. Because epydoc works with tags rather than sections, it looks a lot "noisier" to me when reading the plain text version. Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia --------------------------------------------------------------- From barry at python.org Wed Apr 14 16:07:55 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 10:07:55 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5CA13.7020904@gmail.com> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> Message-ID: <20100414100755.6d321652@heresy> On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: >Barry Warsaw wrote: >> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >> >>> Definite +1 from me on adopting reST in docstrings as a standard. I >>> haven't looked at the Epydoc convention for parameters (etc) well enough >>> to have an opinion on that. >> >> The thing I like about them is that the rules are very simple, and once >> learned are easy to remember. > >Did you look at the NumPy guidelines Ralf posted?: >http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines > >Those look very clean to me, and fairly similar to what we already do in >the ReST docs. > >Because epydoc works with tags rather than sections, it looks a lot >"noisier" to me when reading the plain text version. And I'm not keen on the sections since I think they consume too much vertical whitespace. And I like the tags of epydoc format on the left side for their regularity. Everyone's got a different opinion, and the only one that matters is the BDFL's. :) OTOH, the specifics don't matter as much as just picking one for the stdlib. -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From g.brandl at gmx.net Wed Apr 14 16:23:59 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Wed, 14 Apr 2010 14:23:59 +0000 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414100755.6d321652@heresy> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> Message-ID: Am 14.04.2010 14:07, schrieb Barry Warsaw: > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > >>Barry Warsaw wrote: >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >>> >>>> Definite +1 from me on adopting reST in docstrings as a standard. I >>>> haven't looked at the Epydoc convention for parameters (etc) well enough >>>> to have an opinion on that. >>> >>> The thing I like about them is that the rules are very simple, and once >>> learned are easy to remember. >> >>Did you look at the NumPy guidelines Ralf posted?: >>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines >> >>Those look very clean to me, and fairly similar to what we already do in >>the ReST docs. >> >>Because epydoc works with tags rather than sections, it looks a lot >>"noisier" to me when reading the plain text version. > > And I'm not keen on the sections since I think they consume too much vertical > whitespace. And I like the tags of epydoc format on the left side for their > regularity. Also, the numpy docstring conventions also aren't valid reST and therefore need preprocessing. (Making them reST isn't hard but requires even more vertical space.) Georg From ncoghlan at gmail.com Wed Apr 14 16:27:51 2010 From: ncoghlan at gmail.com (Nick Coghlan) Date: Thu, 15 Apr 2010 00:27:51 +1000 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414081058.29868be4@heresy> References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> <20100414081058.29868be4@heresy> Message-ID: <4BC5D0E7.3020101@gmail.com> Barry Warsaw wrote: > Here's an example: > > def inject_message(mlist, msg, recips=None, switchboard=None, **kws): > """Inject a message into a queue. > > :param mlist: The mailing list this message is destined for. > :type mlist: `IMailingList` > :param msg: The message object to inject. > :type msg: `email.message.Message` or derived > :param recips: Optional set of recipients to put into the message's > metadata. > :type recips: sequence of strings > :param switchboard: Optional name of switchboard to inject this message > into. If not given, the 'in' switchboard is used. > :type switchboard: string > :param kws: Additional values for the message metadata. > :type kws: dictionary > """ Since the NumPy conventions seem to be the only real alternative proposed so far, here's what the above would look like (according to my ever so comprehensive 5 minute skim of those guidelines, anyway...) def inject_message(mlist, msg, recips=None, switchboard=None, **kws): """Inject a message into a queue. Parameters ---------- mlist : IMailingList The mailing list this message is destined for. msg : email.message.Message (or derived) The message object to inject. recips : sequence of strings, optional Optional set of recipients to put into the message's metadata. switchboard : string, optional Optional name of switchboard to inject this message into. If not given, the 'in' switchboard is used. kws : dictionary, optional Additional values for the message metadata. """ Basically, the numpy format trades a couple of lines of whitespace for the section header to get rid of the tag noise in the individual parameter descriptions. The ", optional" parts seem rather redundant (since they are implied by the function signature itself), but the guidelines say to include them, so I included them. It seems to me that the exceptional keyword arguments are those which are required, not those which are optional. Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia --------------------------------------------------------------- From g.brandl at gmx.net Wed Apr 14 16:26:31 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Wed, 14 Apr 2010 14:26:31 +0000 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> Message-ID: Am 14.04.2010 13:08, schrieb Fred Drake: > On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord > wrote: >> I too would prefer a consistent pattern be adopted for the Python standard >> library. Good luck finding someone to go and change all the docstrings in >> the standard library to use it... > > We found someone interested in converting the LaTeX to ReST, didn't we? :-) That was a more interesting task :) However, I'm not opposed to doing stupid, repetitive things every now and then, and I hope I can find a few others to share the task. > If we can come up with a good recommendation, it'll take hold fairly > thoroughly. Not quickly at first, but once there's value (tools) to > be had it'll happen. > > The value for the standard library is that the documentation > maintenance can be moved closer to the code, and is less likely to get > out of sync. Exactly. Georg From fdrake at acm.org Wed Apr 14 16:37:19 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 10:37:19 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5D0E7.3020101@gmail.com> References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> <20100414081058.29868be4@heresy> <4BC5D0E7.3020101@gmail.com> Message-ID: On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan wrote: > The ", optional" parts seem rather redundant (since they are implied by > the function signature itself), but the guidelines say to include them, > so I included them. It seems to me that the exceptional keyword > arguments are those which are required, not those which are optional. This has always been a source of tension in documenting Python: a certain amount of information is available in the signature, but the signature of the implementation function isn't always the same as the signature of the contract. Documentation needs the later. Interfaces help, if you use them (ABCs kinda, if you follow that school of thought). Unfortunately, there's not really a way currently to tell the difference between "default implementation" and "contract" in ABCs, which is all stock Python provides. -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Mille From fuzzyman at voidspace.org.uk Wed Apr 14 16:39:20 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 16:39:20 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> <20100414081058.29868be4@heresy> <4BC5D0E7.3020101@gmail.com> Message-ID: <4BC5D398.80702@voidspace.org.uk> On 14/04/2010 16:37, Fred Drake wrote: > On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan wrote: > >> The ", optional" parts seem rather redundant (since they are implied by >> the function signature itself), but the guidelines say to include them, >> so I included them. It seems to me that the exceptional keyword >> arguments are those which are required, not those which are optional. >> > This has always been a source of tension in documenting Python: a > certain amount of information is available in the signature, but the > signature of the implementation function isn't always the same as the > signature of the contract. Documentation needs the later. > > Interfaces help, if you use them (ABCs kinda, if you follow that > school of thought). Unfortunately, there's not really a way currently > to tell the difference between "default implementation" and "contract" > in ABCs, which is all stock Python provides. > > Right - and included in the contract can be details like what exceptions an API raises. We don't necessarily need a standard to specify that (?) but it is the sort of information that ought to be in docstrings where relevant. Michael > -Fred > > -- http://www.ironpythoninaction.com/ From fdrake at acm.org Wed Apr 14 16:39:07 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 10:39:07 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl wrote: > That was a more interesting task :) ?However, I'm not opposed to doing > stupid, repetitive things every now and then, and I hope I can find a > few others to share the task. Agreed the task was more interesting. Also, I wasn't suggesting that we should sucker you into another such task, but just noting that someone's likely to find the outcome sufficiently valuable. And yes, multiple hands would be better. -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller From fdrake at acm.org Wed Apr 14 16:47:39 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 10:47:39 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5D398.80702@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> <20100414081058.29868be4@heresy> <4BC5D0E7.3020101@gmail.com> <4BC5D398.80702@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 10:39 AM, Michael Foord wrote: > Right - and included in the contract can be details like what exceptions an > API raises. We don't necessarily need a standard to specify that (?) but it > is the sort of information that ought to be in docstrings where relevant. Yep. I was really just wanting to emphasize that extracting information from the signature is likely to be wrong. Unless there's a way to say explicitly that it's right. (Which would require a known interpretation, which isn't really as easy as it sounds.) -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller From ralf.gommers at googlemail.com Wed Apr 14 16:48:13 2010 From: ralf.gommers at googlemail.com (Ralf Gommers) Date: Wed, 14 Apr 2010 22:48:13 +0800 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> Message-ID: On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl wrote: > Am 14.04.2010 14:07, schrieb Barry Warsaw: > > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > > > >>Barry Warsaw wrote: > >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: > >>> > >>>> Definite +1 from me on adopting reST in docstrings as a standard. I > >>>> haven't looked at the Epydoc convention for parameters (etc) well > enough > >>>> to have an opinion on that. > >>> > >>> The thing I like about them is that the rules are very simple, and once > >>> learned are easy to remember. > >> > >>Did you look at the NumPy guidelines Ralf posted?: > >>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines > >> > >>Those look very clean to me, and fairly similar to what we already do in > >>the ReST docs. > >> > >>Because epydoc works with tags rather than sections, it looks a lot > >>"noisier" to me when reading the plain text version. > > > > And I'm not keen on the sections since I think they consume too much > vertical > > whitespace. And I like the tags of epydoc format on the left side for > their > > regularity. > > Also, the numpy docstring conventions also aren't valid reST and therefore > need preprocessing. (Making them reST isn't hard but requires even more > vertical space.) > > The preprocessing should not be an issue, especially since the code for that already exists and is heavily used. The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way. Cheers, Ralf -------------- next part -------------- An HTML attachment was scrubbed... URL: From ralf.gommers at googlemail.com Wed Apr 14 16:53:39 2010 From: ralf.gommers at googlemail.com (Ralf Gommers) Date: Wed, 14 Apr 2010 22:53:39 +0800 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <20100414073845.479aa15d@heresy> <4BC5B893.1050702@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 10:39 PM, Fred Drake wrote: > On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl wrote: > > That was a more interesting task :) However, I'm not opposed to doing > > stupid, repetitive things every now and then, and I hope I can find a > > few others to share the task. > > Agreed the task was more interesting. > > Also, I wasn't suggesting that we should sucker you into another such > task, but just noting that someone's likely to find the outcome > sufficiently valuable. And yes, multiple hands would be better. > > > Pydocweb (http://code.google.com/p/pydocweb/) is very good for this. It's an svn-aware wiki docstring editor. For numpy/scipy about 100 people are registered, most of whom have contributed, from a few bug fixes to thousands of words. A python committer would only need to review changes and apply patches. It's a great way to get contributions from new people. Cheers, Ralf -------------- next part -------------- An HTML attachment was scrubbed... URL: From fuzzyman at voidspace.org.uk Wed Apr 14 16:56:45 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 16:56:45 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> Message-ID: <4BC5D7AD.8080705@voidspace.org.uk> On 14/04/2010 16:48, Ralf Gommers wrote: > > > On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl > wrote: > > Am 14.04.2010 14:07, schrieb Barry Warsaw: > > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > > > >>Barry Warsaw wrote: > >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: > >>> > >>>> Definite +1 from me on adopting reST in docstrings as a > standard. I > >>>> haven't looked at the Epydoc convention for parameters (etc) > well enough > >>>> to have an opinion on that. > >>> > >>> The thing I like about them is that the rules are very simple, > and once > >>> learned are easy to remember. > >> > >>Did you look at the NumPy guidelines Ralf posted?: > >>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines > >> > >>Those look very clean to me, and fairly similar to what we > already do in > >>the ReST docs. > >> > >>Because epydoc works with tags rather than sections, it looks a lot > >>"noisier" to me when reading the plain text version. > > > > And I'm not keen on the sections since I think they consume too > much vertical > > whitespace. And I like the tags of epydoc format on the left > side for their > > regularity. > > Also, the numpy docstring conventions also aren't valid reST and > therefore > need preprocessing. (Making them reST isn't hard but requires > even more > vertical space.) > > The preprocessing should not be an issue, especially since the code > for that already exists and is heavily used. > > The vertical whitespace vs tags is a taste issue, I agree, from a > developer perspective. From a user perspective however, the numpy > standard is clearly more readable in a terminal. That's why it looks > the way it does. And reading docstrings in a terminal is not a fringe > use case by the way. I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way. Michael > > Cheers, > Ralf > > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From ralf.gommers at googlemail.com Wed Apr 14 17:13:15 2010 From: ralf.gommers at googlemail.com (Ralf Gommers) Date: Wed, 14 Apr 2010 23:13:15 +0800 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5D7AD.8080705@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord wrote: > On 14/04/2010 16:48, Ralf Gommers wrote: > > The vertical whitespace vs tags is a taste issue, I agree, from a developer > perspective. From a user perspective however, the numpy standard is clearly > more readable in a terminal. That's why it looks the way it does. And > reading docstrings in a terminal is not a fringe use case by the way. > > I would say that reading docstrings in a terminal is the *main* use case - > but that is why I tend to value the vertical space highly and personally > prefer the less verbose way. > You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability. Ralf -------------- next part -------------- An HTML attachment was scrubbed... URL: From fuzzyman at voidspace.org.uk Wed Apr 14 17:22:26 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 17:22:26 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> Message-ID: <4BC5DDB2.7010608@voidspace.org.uk> On 14/04/2010 17:13, Ralf Gommers wrote: > > > On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord > > wrote: > > On 14/04/2010 16:48, Ralf Gommers wrote: >> The vertical whitespace vs tags is a taste issue, I agree, from a >> developer perspective. From a user perspective however, the numpy >> standard is clearly more readable in a terminal. That's why it >> looks the way it does. And reading docstrings in a terminal is >> not a fringe use case by the way. > I would say that reading docstrings in a terminal is the *main* > use case - but that is why I tend to value the vertical space > highly and personally prefer the less verbose way. > > > You're a core developer (I think). But for the *average* user, do you > really think tags are fine? Earlier in this thread there was a mention > of people that love to read XML. I'm exaggerating a bit of course, but > this is similar. Whitespace beats tags for readability. > Well, docstrings that take up several screens worth of console and scroll out of view like merry abandon are horrible. We should do real usability testing (with 'real' users) if we really want an answer. Michael > Ralf > -- http://www.ironpythoninaction.com/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From fdrake at acm.org Wed Apr 14 17:24:21 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 11:24:21 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers wrote: > You're a core developer (I think). But for the *average* user, do you really > think tags are fine? Earlier in this thread there was a mention of people > that love to read XML. I'm exaggerating a bit of course, but this is > similar. Whitespace beats tags for readability. All consumers of docstrings are programmers. Maybe only by necessity, but they are. Frankly, terminals and any other window just can't handle all that much text on the typical horizontal monitor, placing a premium on vertical whitespace. Widescreen is good for movies, but sucks for general-purpose computer monitors. -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller From fuzzyman at voidspace.org.uk Wed Apr 14 17:25:45 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 17:25:45 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> Message-ID: <4BC5DE79.3030403@voidspace.org.uk> On 14/04/2010 17:24, Fred Drake wrote: > On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers > wrote: > >> You're a core developer (I think). But for the *average* user, do you really >> think tags are fine? Earlier in this thread there was a mention of people >> that love to read XML. I'm exaggerating a bit of course, but this is >> similar. Whitespace beats tags for readability. >> > All consumers of docstrings are programmers. Maybe only by necessity, > but they are. > > Frankly, terminals and any other window just can't handle all that > much text on the typical horizontal monitor, placing a premium on > vertical whitespace. > > Widescreen is good for movies, but sucks for general-purpose computer monitors. > They're great if you turn them sideways though... Michael > > -Fred > > -- http://www.ironpythoninaction.com/ From fdrake at acm.org Wed Apr 14 17:29:12 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 11:29:12 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5DE79.3030403@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DE79.3030403@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 11:25 AM, Michael Foord wrote: > They're great if you turn them sideways though... Indeed they are! All monitors are improved in that arrangement. -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller From ralf.gommers at googlemail.com Wed Apr 14 17:35:22 2010 From: ralf.gommers at googlemail.com (Ralf Gommers) Date: Wed, 14 Apr 2010 23:35:22 +0800 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5DDB2.7010608@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DDB2.7010608@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 11:22 PM, Michael Foord wrote: > On 14/04/2010 17:13, Ralf Gommers wrote: > > > > On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord > wrote: > >> On 14/04/2010 16:48, Ralf Gommers wrote: >> >> The vertical whitespace vs tags is a taste issue, I agree, from a >> developer perspective. From a user perspective however, the numpy standard >> is clearly more readable in a terminal. That's why it looks the way it does. >> And reading docstrings in a terminal is not a fringe use case by the way. >> >> I would say that reading docstrings in a terminal is the *main* use case >> - but that is why I tend to value the vertical space highly and personally >> prefer the less verbose way. >> > > You're a core developer (I think). But for the *average* user, do you > really think tags are fine? Earlier in this thread there was a mention of > people that love to read XML. I'm exaggerating a bit of course, but this is > similar. Whitespace beats tags for readability. > > > Well, docstrings that take up several screens worth of console and scroll > out of view like merry abandon are horrible. > In many cases yes, but that is a totally different issue. The example Nick posted was 17 lines for numpy standard vs 15 lines for epydoc standard. > We should do real usability testing (with 'real' users) if we really want > an answer. > > That sounds like a good idea. Cheers, Ralf -------------- next part -------------- An HTML attachment was scrubbed... URL: From fuzzyman at voidspace.org.uk Wed Apr 14 17:37:28 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 17:37:28 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414100755.6d321652@heresy> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> Message-ID: <4BC5E138.20101@voidspace.org.uk> On 14/04/2010 16:07, Barry Warsaw wrote: > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > > >> Barry Warsaw wrote: >> >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >>> >>> >>>> Definite +1 from me on adopting reST in docstrings as a standard. I >>>> haven't looked at the Epydoc convention for parameters (etc) well enough >>>> to have an opinion on that. >>>> >>> The thing I like about them is that the rules are very simple, and once >>> learned are easy to remember. >>> >> Did you look at the NumPy guidelines Ralf posted?: >> http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines >> >> Those look very clean to me, and fairly similar to what we already do in >> the ReST docs. >> >> Because epydoc works with tags rather than sections, it looks a lot >> "noisier" to me when reading the plain text version. >> > And I'm not keen on the sections since I think they consume too much vertical > whitespace. And I like the tags of epydoc format on the left side for their > regularity. Everyone's got a different opinion, and the only one that matters > is the BDFL's. :) > Well, perhaps move this discussion to python-dev with the intent of creating a PEP and asking for BDFL pronouncement? The two contenders seem to be numpy format and epydoc format. We seem to have a consensus that adopting a standard for the standard library is a good idea. Once we have settled on a basic format we can thrash out all the specifics in the PEP. All the best, Michael > OTOH, the specifics don't matter as much as just picking one for the stdlib. > > -Barry > > -- http://www.ironpythoninaction.com/ From barry at python.org Wed Apr 14 17:41:42 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 11:41:42 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5D7AD.8080705@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> Message-ID: <20100414114142.421d6482@heresy> On Apr 14, 2010, at 04:56 PM, Michael Foord wrote: >I would say that reading docstrings in a terminal is the *main* use case >- but that is why I tend to value the vertical space highly and >personally prefer the less verbose way. I agree about the vertical whitespace when reading in the terminal. You also want compact output for online docs too though. I'm tempted to say that whatever Georg implements in Sphinx is good enough for me. :) -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From barry at python.org Wed Apr 14 17:43:49 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 11:43:49 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> Message-ID: <20100414114349.304cae1d@heresy> On Apr 14, 2010, at 11:13 PM, Ralf Gommers wrote: >You're a core developer (I think). But for the *average* user, do you really >think tags are fine? Earlier in this thread there was a mention of people >that love to read XML. I'm exaggerating a bit of course, but this is >similar. Whitespace beats tags for readability. Well, I would think that help output, whether in a terminal or online would use the raw text to do a nicer job of formatting. It's source code readability that concerns me. -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From barry at python.org Wed Apr 14 17:46:43 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 11:46:43 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5E138.20101@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5E138.20101@voidspace.org.uk> Message-ID: <20100414114643.636b7103@heresy> On Apr 14, 2010, at 05:37 PM, Michael Foord wrote: >Well, perhaps move this discussion to python-dev with the intent of >creating a PEP and asking for BDFL pronouncement? The two contenders >seem to be numpy format and epydoc format. We seem to have a consensus >that adopting a standard for the standard library is a good idea. > >Once we have settled on a basic format we can thrash out all the >specifics in the PEP. I agree. Right now I've got enough big PEPs on my plate that I'm not willing to take on another one right now. Maybe I've sufficiently tempted/goaded/guilted/excited someone else to though. ;) -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From marysbook119 at charter.net Wed Apr 14 17:46:11 2010 From: marysbook119 at charter.net (Mary S. Murphy) Date: Wed, 14 Apr 2010 11:46:11 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk><20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com><20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DDB2.7010608@voidspace.org.uk> Message-ID: <59B88FF53B014A84B84B322C52AAA787@n1c807d33a5344> Please get your email addresses correct. I keep getting them. Thanks. ----- Original Message ----- From: Michael Foord To: Ralf Gommers Cc: doc-sig at python.org Sent: Wednesday, April 14, 2010 11:22 AM Subject: Re: [Doc-SIG] epydoc reST markup for stdlib docstrings On 14/04/2010 17:13, Ralf Gommers wrote: On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord wrote: On 14/04/2010 16:48, Ralf Gommers wrote: The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspective however, the numpy standard is clearly more readable in a terminal. That's why it looks the way it does. And reading docstrings in a terminal is not a fringe use case by the way. I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way. You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit of course, but this is similar. Whitespace beats tags for readability. Well, docstrings that take up several screens worth of console and scroll out of view like merry abandon are horrible. We should do real usability testing (with 'real' users) if we really want an answer. Michael Ralf -- http://www.ironpythoninaction.com/ ------------------------------------------------------------------------------ _______________________________________________ Doc-SIG maillist - Doc-SIG at python.org http://mail.python.org/mailman/listinfo/doc-sig -------------- next part -------------- An HTML attachment was scrubbed... URL: From g.brandl at gmx.net Wed Apr 14 17:53:48 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Wed, 14 Apr 2010 15:53:48 +0000 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <4BC5DE79.3030403@voidspace.org.uk> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DE79.3030403@voidspace.org.uk> Message-ID: Am 14.04.2010 15:25, schrieb Michael Foord: > On 14/04/2010 17:24, Fred Drake wrote: >> On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers >> wrote: >> >>> You're a core developer (I think). But for the *average* user, do you really >>> think tags are fine? Earlier in this thread there was a mention of people >>> that love to read XML. I'm exaggerating a bit of course, but this is >>> similar. Whitespace beats tags for readability. >>> >> All consumers of docstrings are programmers. Maybe only by necessity, >> but they are. >> >> Frankly, terminals and any other window just can't handle all that >> much text on the typical horizontal monitor, placing a premium on >> vertical whitespace. >> >> Widescreen is good for movies, but sucks for general-purpose computer monitors. >> > They're great if you turn them sideways though... Uh, or just use an editor that can usefully display three files side-by-side. not-name-dropping-ly y'rs, Georg From fuzzyman at voidspace.org.uk Wed Apr 14 17:59:24 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 17:59:24 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414114142.421d6482@heresy> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <20100414114142.421d6482@heresy> Message-ID: <4BC5E65C.1010402@voidspace.org.uk> On 14/04/2010 17:41, Barry Warsaw wrote: > On Apr 14, 2010, at 04:56 PM, Michael Foord wrote: > > >> I would say that reading docstrings in a terminal is the *main* use case >> - but that is why I tend to value the vertical space highly and >> personally prefer the less verbose way. >> > I agree about the vertical whitespace when reading in the terminal. You also > want compact output for online docs too though. > > I'm tempted to say that whatever Georg implements in Sphinx is good enough for > me. :) > I completely agree that Georg is the man to take this forward and complete the task... :-) Michael > -Barry > > > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From fuzzyman at voidspace.org.uk Wed Apr 14 18:04:22 2010 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Wed, 14 Apr 2010 18:04:22 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DE79.3030403@voidspace.org.uk> Message-ID: <4BC5E786.5080202@voidspace.org.uk> On 14/04/2010 17:53, Georg Brandl wrote: > Am 14.04.2010 15:25, schrieb Michael Foord: > >> On 14/04/2010 17:24, Fred Drake wrote: >> >>> On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers >>> wrote: >>> >>> >>>> You're a core developer (I think). But for the *average* user, do you really >>>> think tags are fine? Earlier in this thread there was a mention of people >>>> that love to read XML. I'm exaggerating a bit of course, but this is >>>> similar. Whitespace beats tags for readability. >>>> >>>> >>> All consumers of docstrings are programmers. Maybe only by necessity, >>> but they are. >>> >>> Frankly, terminals and any other window just can't handle all that >>> much text on the typical horizontal monitor, placing a premium on >>> vertical whitespace. >>> >>> Widescreen is good for movies, but sucks for general-purpose computer monitors. >>> >>> >> They're great if you turn them sideways though... >> > Uh, or just use an editor that can usefully display three files side-by-side. > > Like Wing? http://skitch.com/fuzzyman/n6581/wing-ide-vera-backend.wpr-views.py-vera-mailing Michael > not-name-dropping-ly y'rs, > Georg > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ From fdrake at acm.org Wed Apr 14 18:36:41 2010 From: fdrake at acm.org (Fred Drake) Date: Wed, 14 Apr 2010 12:36:41 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DE79.3030403@voidspace.org.uk> Message-ID: On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl wrote: > Uh, or just use an editor that can usefully display three files side-by-side. Hmmm... Three monitors, each with three files side by side, oriented vertically. More monitors for email and browsers, of course. Sounds like an ideal coding platform to me! -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller From amk at amk.ca Wed Apr 14 18:00:52 2010 From: amk at amk.ca (A.M. Kuchling) Date: Wed, 14 Apr 2010 12:00:52 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <59B88FF53B014A84B84B322C52AAA787@n1c807d33a5344> References: <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DDB2.7010608@voidspace.org.uk> <59B88FF53B014A84B84B322C52AAA787@n1c807d33a5344> Message-ID: <20100414160052.GA4937@amk-desktop.matrixgroup.net> On Wed, Apr 14, 2010 at 11:46:11AM -0400, Mary S. Murphy wrote: > Please get your email addresses correct. I keep getting them. Thanks. I've removed her from the list. --amk From janssen at parc.com Wed Apr 14 18:59:40 2010 From: janssen at parc.com (Bill Janssen) Date: Wed, 14 Apr 2010 09:59:40 PDT Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DE79.3030403@voidspace.org.uk> Message-ID: <44101.1271264380@parc.com> Fred Drake wrote: > On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl wrote: > > Uh, or just use an editor that can usefully display three files side-by-side. > > Hmmm... Three monitors, each with three files side by side, oriented > vertically. More monitors for email and browsers, of course. Sounds > like an ideal coding platform to me! I've been using this for a bit -- three 1200x1600 monitors in portrait mode driven by a Mac Pro. Not bad, but at my boss's urging I've recently replaced two of them with an Apple 30" Cinema display. Bit more resolution, 2560x1600, but I find the absence of the gap is a good thing. Bill From g.brandl at gmx.net Wed Apr 14 23:50:11 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Wed, 14 Apr 2010 23:50:11 +0200 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414114643.636b7103@heresy> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5E138.20101@voidspace.org.uk> <20100414114643.636b7103@heresy> Message-ID: Am 14.04.2010 17:46, schrieb Barry Warsaw: > On Apr 14, 2010, at 05:37 PM, Michael Foord wrote: > >>Well, perhaps move this discussion to python-dev with the intent of >>creating a PEP and asking for BDFL pronouncement? The two contenders >>seem to be numpy format and epydoc format. We seem to have a consensus >>that adopting a standard for the standard library is a good idea. >> >>Once we have settled on a basic format we can thrash out all the >>specifics in the PEP. > > I agree. Right now I've got enough big PEPs on my plate that I'm not willing > to take on another one right now. Maybe I've sufficiently > tempted/goaded/guilted/excited someone else to though. ;) Yes, I'll write that PEP. Don't expect it too soon though. cheers, Georg From barry at python.org Thu Apr 15 00:27:30 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 18:27:30 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5E138.20101@voidspace.org.uk> <20100414114643.636b7103@heresy> Message-ID: <20100414182730.2ac2de15@heresy> On Apr 14, 2010, at 11:50 PM, Georg Brandl wrote: >Am 14.04.2010 17:46, schrieb Barry Warsaw: >> I agree. Right now I've got enough big PEPs on my plate that I'm not >> willing to take on another one right now. Maybe I've sufficiently >> tempted/goaded/guilted/excited someone else to though. ;) > >Yes, I'll write that PEP. Don't expect it too soon though. My evil plan worked! :) Thanks Georg. -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From barry at python.org Thu Apr 15 00:28:43 2010 From: barry at python.org (Barry Warsaw) Date: Wed, 14 Apr 2010 18:28:43 -0400 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <44101.1271264380@parc.com> References: <20100413171219.7a2c10a2@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <4BC5DE79.3030403@voidspace.org.uk> <44101.1271264380@parc.com> Message-ID: <20100414182843.413394c6@heresy> On Apr 14, 2010, at 09:59 AM, Bill Janssen wrote: >I've been using this for a bit -- three 1200x1600 monitors in portrait >mode driven by a Mac Pro. Not bad, but at my boss's urging I've >recently replaced two of them with an Apple 30" Cinema display. Bit >more resolution, 2560x1600, but I find the absence of the gap is a good >thing. I'm pretty sure I hate you now. :) -Barry -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 836 bytes Desc: not available URL: From ralf.gommers at googlemail.com Thu Apr 15 12:39:05 2010 From: ralf.gommers at googlemail.com (Ralf Gommers) Date: Thu, 15 Apr 2010 18:39:05 +0800 Subject: [Doc-SIG] epydoc reST markup for stdlib docstrings In-Reply-To: <20100414114349.304cae1d@heresy> References: <20100413171219.7a2c10a2@heresy> <4BC4FE8B.6020604@voidspace.org.uk> <20100413204047.4502b11e@heresy> <4BC5CA13.7020904@gmail.com> <20100414100755.6d321652@heresy> <4BC5D7AD.8080705@voidspace.org.uk> <20100414114349.304cae1d@heresy> Message-ID: On Wed, Apr 14, 2010 at 11:43 PM, Barry Warsaw wrote: > On Apr 14, 2010, at 11:13 PM, Ralf Gommers wrote: > > >You're a core developer (I think). But for the *average* user, do you > really > >think tags are fine? Earlier in this thread there was a mention of people > >that love to read XML. I'm exaggerating a bit of course, but this is > >similar. Whitespace beats tags for readability. > > Well, I would think that help output, whether in a terminal or online would > use the raw text to do a nicer job of formatting. If it looks good in help() (and ipython) then I have no problem with it. You would have to preprocess each docstring each time it's viewed though, instead of only when generating html docs. But if it's robust, then sure, it's a non-issue. Cheers, Ralf -------------- next part -------------- An HTML attachment was scrubbed... URL: