From rrr at ronadam.com Mon Sep 1 00:41:57 2008 From: rrr at ronadam.com (Ron Adam) Date: Sun, 31 Aug 2008 17:41:57 -0500 Subject: [Doc-SIG] What to do next for 2.6? In-Reply-To: <48BAECF2.8050300@ronadam.com> References: <20080831182204.GA8152@amk.local> <48BAECF2.8050300@ronadam.com> Message-ID: <48BB1E35.608@ronadam.com> The patch is updated for 2.6. http://bugs.python.org/issue2001 Ron Ron Adam wrote: > > > A.M. Kuchling wrote: >> This weekend I made a final revision pass over the 2.6 "What's New" >> document and am now finished with it (barring any small corrections or >> omissions that come in). >> >> What should I do now with my Python doc time? Georg, do you have any >> suggestions? I could start reading through one of the manuals from >> end-to-end or go through the bug tracker for doc items. Are there any >> writing-related tasks you've been meaning to do before 2.6final? > > I'm presuming you are referring to content related items, but I fugures > it doesn't hurt to ask. > > > A while back I wrote a patch to enhance pydoc. > > http://bugs.python.org/issue2001 > > > I figured it would need to wait until 2.7/3.1, is > there any chance of getting it in before then? > > > I probably need to updated it again so it will apply properly as there > has been other fixes/patches to pydoc. > > Ron > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > From fdrake at acm.org Wed Sep 17 01:10:59 2008 From: fdrake at acm.org (Fred Drake) Date: Tue, 16 Sep 2008 19:10:59 -0400 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: References: <20080620124140.GA6015@amk-desktop.matrixgroup.net> Message-ID: [Just noticed this old conversation.] On Jun 22, 2008, at 7:36 AM, Georg Brandl wrote: > I'm +0. I'd like to hear Fred's opinion since (I guess) he > introduced the > nested bracket notation. If he's okay with it, I'll write a script > that > converts the signatures in the whole documentation. Hmm. I'm fairly certain I didn't create it, but at this point, I might be mistaken. The nested notation makes sense for optional arguments, especially where keywords aren't supported. This is still the case for many of the APIs written in C, and those cases often won't be changed due to performance considerations. (Adding keyword support definitely slows things down.) For code implemented in Python, it's less of an issue, since the keyword support is always there unless the author of the code went out of the way to avoid it (using *args, for example). This happens, but isn't very common. But that's part of my reservation about this. With the nested notation, it's possible to specify signatures that are different from the implementation signatures. I think that's valuable still. So I guess now someone will tell me this has already been changed, and I missed it. --sigh-- -Fred -- Fred Drake From amk at amk.ca Wed Sep 24 19:21:48 2008 From: amk at amk.ca (A.M. Kuchling) Date: Wed, 24 Sep 2008 13:21:48 -0400 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: References: <20080620124140.GA6015@amk-desktop.matrixgroup.net>

Message-ID: <20080924172148.GA11911@amk-desktop.matrixgroup.net> On Tue, Sep 16, 2008 at 07:10:59PM -0400, Fred Drake wrote: > The nested notation makes sense for optional arguments, especially where > keywords aren't supported. This is still the case for many of the APIs > written in C, and those cases often won't be changed due to performance > considerations. (Adding keyword support definitely slows things down.) So, the use cases are: * Python code where arguments are both optional and specifiable as a keyword argument. * C code where keywords are supported. * C code where keywords are not supported. I think nesting the optional arguments doesn't actually indicate whether keywords are supported or not. For example, two functions from the socket module are: .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]]) .. method:: socket.recv_into(buffer[, nbytes[, flags]]) getaddrinfo() doesn't support keyword arguments; recv_into() does. But nesting the brackets does add a lot of typographical fluff. Can we invent a new notation for separating which functions support keywords and which don't? How would we render that distinction typographically in the output? Ideas: * Boldface parameters that can be provided as keywords. * Add '=' after parameters that can be provided as keywords: buffer=, [nbytes=, flags=] ... * Write keyword arguments as unnested square brackets: (buffer[, nbytes][, flags]) This reserves the nesting for functions that don't support keywords. I think the difflib docs are mostly written in this style. > So I guess now someone will tell me this has already been changed, and I > missed it. No, no one's made any changes relating to this yet. --amk From the.blue.valkyrie at gmail.com Thu Sep 25 01:58:45 2008 From: the.blue.valkyrie at gmail.com (=?ISO-8859-1?Q?Cristina_Yenyxe_Gonz=E1lez_Garc=EDa?=) Date: Thu, 25 Sep 2008 01:58:45 +0200 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: <20080924172148.GA11911@amk-desktop.matrixgroup.net> References: <20080620124140.GA6015@amk-desktop.matrixgroup.net>

<20080924172148.GA11911@amk-desktop.matrixgroup.net> Message-ID: 2008/9/24 A.M. Kuchling : > On Tue, Sep 16, 2008 at 07:10:59PM -0400, Fred Drake wrote: > > I think nesting the optional arguments doesn't actually indicate > whether keywords are supported or not. For example, > two functions from the socket module are: > > .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]]) > .. method:: socket.recv_into(buffer[, nbytes[, flags]]) > > getaddrinfo() doesn't support keyword arguments; recv_into() does. > But nesting the brackets does add a lot of typographical fluff. > > Can we invent a new notation for separating which functions support > keywords and which don't? How would we render that distinction > typographically in the output? > I would like to suggest an idea which wouldn't involve typographical changes. I think keyword arguments could be represented just if they were in a dictionary, something like: buffer, **{nbytes, flags} Maybe it would take some time for the people to get used to the new syntax, but I think is it, at least, similar to Python code. From g.brandl at gmx.net Thu Sep 25 14:45:30 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Thu, 25 Sep 2008 14:45:30 +0200 Subject: [Doc-SIG] Docs search improved Message-ID: The docs search now searches for objects whose name contains the search word before doing full-text search. Please let me know if it works as expected. 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. From list8a.forest at tibit.com Thu Sep 25 19:08:06 2008 From: list8a.forest at tibit.com (Forest) Date: Thu, 25 Sep 2008 10:08:06 -0700 (PDT) Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: References: Message-ID: <21467.75.55.199.5.1222362486.squirrel@webmail.sonic.net> On Wed, September 24, 2008 10:21 am, A.M. Kuchling wrote: > > .. method:: socket.recv_into(buffer[, nbytes[, flags]]) Straying slightly from the issue of keyword arguments, I'd like to point out that the nested brackets imply to me that the flags arg requires the nbytes arg to be present as well. Compare to your suggestions: > * Add '=' after parameters that can be provided as keywords: > buffer=, [nbytes=, flags=] ... > > * Write keyword arguments as unnested square brackets: > (buffer[, nbytes][, flags]) Neither of those notations conveys a dependence of one argument on the other. From g.brandl at gmx.net Thu Sep 25 21:15:42 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Thu, 25 Sep 2008 21:15:42 +0200 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: <20080620124140.GA6015@amk-desktop.matrixgroup.net> References: <20080620124140.GA6015@amk-desktop.matrixgroup.net> Message-ID: A.M. Kuchling schrieb: > To show a series of optional parameters, currently we nest square > brackets. > > http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings > > warnings.filterwarnings(action[, message[, category[, module[, > lineno[, append]]]]]) > > My proposal is that we drop the nesting and write this as: > > warnings.filterwarnings(action [, message, category, module, lineno, append]) > > Currently the stylesheets make the brackets very big and dark, so I've > also added a space before the bracket. > > This change means we'd lose the ability to show when two optional > arguments must be supplied at the same time, which could currently be > written like this: > > warnings.filterwarnings(action[, message, category[, module]]) > What does everyone think? My proposal: Since we already give a Python-like signature, why not give the full signature for Python functions? That is, simply show default values for arguments like warnings.filterwarnings(action, message="", category=Warning, module="", lineno=0, append=0) That way, we also can get rid of awkward tons of parenthetical remarks like in "If foo is None (which is the default)", and also get to add that information in the first place where it was missing before. The argument defaults can be shown in a different typographical style if desired. Parameters whose default isn't easily displayable can continue to use the brackets. For C module functions that don't support keyword arguments, the old way of nested brackets precisely represents how to call the function, so it should stay. Sadly, this proposal is also the most work-intensive one since no automatic conversion is possible. This being the docs, it is however possible to tackle this over time on a per-module basis, so this is not necessarily a killer argument. 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. From fuzzyman at voidspace.org.uk Thu Sep 25 22:21:44 2008 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Thu, 25 Sep 2008 21:21:44 +0100 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: References: <20080620124140.GA6015@amk-desktop.matrixgroup.net> Message-ID: <48DBF2D8.2060709@voidspace.org.uk> Georg Brandl wrote: > A.M. Kuchling schrieb: > >> To show a series of optional parameters, currently we nest square >> brackets. >> >> http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings >> >> warnings.filterwarnings(action[, message[, category[, module[, >> lineno[, append]]]]]) >> >> My proposal is that we drop the nesting and write this as: >> >> warnings.filterwarnings(action [, message, category, module, lineno, append]) >> >> Currently the stylesheets make the brackets very big and dark, so I've >> also added a space before the bracket. >> >> This change means we'd lose the ability to show when two optional >> arguments must be supplied at the same time, which could currently be >> written like this: >> >> warnings.filterwarnings(action[, message, category[, module]]) >> > > >> What does everyone think? >> > > My proposal: Since we already give a Python-like signature, why not give the > full signature for Python functions? That is, simply show default values for > arguments like > > warnings.filterwarnings(action, message="", category=Warning, module="", > lineno=0, append=0) > > That way, we also can get rid of awkward tons of parenthetical remarks like > in "If foo is None (which is the default)", and also get to add that information > in the first place where it was missing before. > > The argument defaults can be shown in a different typographical style if > desired. Parameters whose default isn't easily displayable can continue to use > the brackets. > > For C module functions that don't support keyword arguments, the old way of > nested brackets precisely represents how to call the function, so it should > stay. > > Sadly, this proposal is also the most work-intensive one since no automatic > conversion is possible. This being the docs, it is however possible to tackle > this over time on a per-module basis, so this is not necessarily a killer > argument. > > +1 It is the most easily understood format by Python programmers for obvious reasons. Actually static code analysis should be able to automate this (or even live introspection). Michael > Georg > > -- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/ http://www.trypython.org/ http://www.ironpython.info/ http://www.theotherdelia.co.uk/ http://www.resolverhacks.net/ From rrr at ronadam.com Fri Sep 26 15:53:47 2008 From: rrr at ronadam.com (Ron Adam) Date: Fri, 26 Sep 2008 08:53:47 -0500 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: References: <20080620124140.GA6015@amk-desktop.matrixgroup.net> Message-ID: <48DCE96B.7090703@ronadam.com> Georg Brandl wrote: > My proposal: Since we already give a Python-like signature, why not give the > full signature for Python functions? That is, simply show default values for > arguments like > > warnings.filterwarnings(action, message="", category=Warning, module="", > lineno=0, append=0) > > That way, we also can get rid of awkward tons of parenthetical remarks like > in "If foo is None (which is the default)", and also get to add that information > in the first place where it was missing before. > > The argument defaults can be shown in a different typographical style if > desired. Parameters whose default isn't easily displayable can continue to use > the brackets. I think that would be fine. Maybe a separate section can be added on the topic of understanding function arguments that uses the nested bracketed forms to help users understand python signatures. I was hoping at some point we might be able to generate the signatures and summary automatically from the source, and merge in the discussion and examples. But currently generating signatures isn't possible for all functions. BTW... Have you tried out the pydoc patch I submitted George? I haven't got any feedback on it yet, so it's just sitting there gathering dust. http://bugs.python.org/issue2001 Ron > For C module functions that don't support keyword arguments, the old way of > nested brackets precisely represents how to call the function, so it should > stay. > > Sadly, this proposal is also the most work-intensive one since no automatic > conversion is possible. This being the docs, it is however possible to tackle > this over time on a per-module basis, so this is not necessarily a killer > argument. > > Georg >