Re: Survey: improving the Python std lib docs

2017-05-22 Thread rzed
A portion of this thread seems to be focusing on what key word args parameters actually mean, in the Python sense. There is documentation for that, and a modicum of experience with Python makes this a relatively simple question and answer. However, when docs for a specific function or method

RE: Survey: improving the Python std lib docs

2017-05-18 Thread Deborah Swanson
> -Original Message- > From: Python-list > [mailto:python-list-bounces+python=deborahswanson.net@python.o > rg] On Behalf Of Gregory Ewing > Sent: Thursday, May 18, 2017 5:00 PM > To: python-list@python.org > Subject: Re: Survey: improving the Python std lib docs &g

Re: Survey: improving the Python std lib docs

2017-05-18 Thread Gregory Ewing
Deborah Swanson wrote: somenamedtuple._replace(kwargs) Return a new instance of the named tuple replacing specified fields with new values: (Examples box)---| |>>> | | | |>>> p = Point(x=11, y=22) | |>>>

RE: Survey: improving the Python std lib docs

2017-05-18 Thread Deborah Swanson
justin walters wrote, on Thursday, May 18, 2017 8:09 AM > To: python-list@python.org > Subject: Re: Survey: improving the Python std lib docs > > So, args can be treated as a simple (named)? tuple or a > simple dictionary. `*` unpacks a list or tuple and `**` > unpacks a di

Re: Survey: improving the Python std lib docs

2017-05-18 Thread justin walters
On Thu, May 18, 2017 at 8:08 AM, justin walters wrote: > > > On Thu, May 18, 2017 at 12:09 AM, Deborah Swanson < > pyt...@deborahswanson.net> wrote: > >> Michael Torrie wrote, on Wednesday, May 17, 2017 3:11 PM >> > >> > On 05/17/2017 02:31 PM, Ned Batchelder wrote:

Re: Survey: improving the Python std lib docs

2017-05-18 Thread justin walters
On Thu, May 18, 2017 at 12:09 AM, Deborah Swanson wrote: > Michael Torrie wrote, on Wednesday, May 17, 2017 3:11 PM > > > > On 05/17/2017 02:31 PM, Ned Batchelder wrote: > > > Can you give an example of such a method? Often, that signature is > > > used because there

RE: Survey: improving the Python std lib docs

2017-05-18 Thread Deborah Swanson
Michael Torrie wrote, on Wednesday, May 17, 2017 3:11 PM > > On 05/17/2017 02:31 PM, Ned Batchelder wrote: > > Can you give an example of such a method? Often, that signature is > > used because there is no pre-conception of what the arguments might > > be. > > I'm not sure if this afflicts

Re: Survey: improving the Python std lib docs

2017-05-17 Thread Chris Angelico
On Thu, May 18, 2017 at 8:11 AM, Michael Torrie wrote: > On 05/17/2017 02:31 PM, Ned Batchelder wrote: >> Can you give an example of such a method? Often, that signature is used >> because there is no pre-conception of what the arguments might be. > > I'm not sure if this

Re: Survey: improving the Python std lib docs

2017-05-17 Thread Michael Torrie
On 05/17/2017 02:31 PM, Ned Batchelder wrote: > Can you give an example of such a method? Often, that signature is used > because there is no pre-conception of what the arguments might be. I'm not sure if this afflicts the standard library, but in my own code, since Python doesn't support

Re: Survey: improving the Python std lib docs

2017-05-17 Thread Ned Batchelder
On Wednesday, May 17, 2017 at 5:48:30 AM UTC-4, Cem Karan wrote: > On May 16, 2017, at 12:36 PM, rzed wrote: > > > On Friday, May 12, 2017 at 6:02:58 AM UTC-4, Steve D'Aprano wrote: > >> One of the more controversial aspects of the Python ecosystem is the Python > >> docs.

RE: Survey: improving the Python std lib docs

2017-05-17 Thread Deborah Swanson
Cem Karan wrote, on Wednesday, May 17, 2017 2:48 AM > > On May 16, 2017, at 12:36 PM, rzed wrote: > > > On Friday, May 12, 2017 at 6:02:58 AM UTC-4, Steve D'Aprano wrote: > >> One of the more controversial aspects of the Python > ecosystem is the > >> Python docs. Some

Re: Survey: improving the Python std lib docs

2017-05-17 Thread Cem Karan
On May 16, 2017, at 12:36 PM, rzed wrote: > On Friday, May 12, 2017 at 6:02:58 AM UTC-4, Steve D'Aprano wrote: >> One of the more controversial aspects of the Python ecosystem is the Python >> docs. Some people love them, and some people hate them and describe them as >>

Re: Survey: improving the Python std lib docs

2017-05-16 Thread rzed
On Friday, May 12, 2017 at 6:02:58 AM UTC-4, Steve D'Aprano wrote: > One of the more controversial aspects of the Python ecosystem is the Python > docs. Some people love them, and some people hate them and describe them as > horrible. > [...] One thing I would love to see in any function or

Re: Survey: improving the Python std lib docs

2017-05-16 Thread Marco Buttu
On 15/05/2017 13:44, Ned Batchelder wrote: As it is, if I make a suggestion about the itertools docs (why do we need 20-line "equivalent to" Python code, and why don't we have any usage examples?), then I have to debate it with the developer of itertools, who has a different aesthetic and style

Re: Survey: improving the Python std lib docs

2017-05-15 Thread Ned Batchelder
On Friday, May 12, 2017 at 6:02:58 AM UTC-4, Steve D'Aprano wrote: > One of the more controversial aspects of the Python ecosystem is the Python > docs. Some people love them, and some people hate them and describe them as > horrible. > I have a number of ideas for improving the docs, but I

Re: Survey: improving the Python std lib docs

2017-05-14 Thread jeanbigboute
On Saturday, May 13, 2017 at 3:39:52 PM UTC-7, Terry Reedy wrote: > On 5/13/2017 1:23 PM, jeanbigbo...@gmail.com wrote: > > > Thank you for bringing up this important topic. As an occasional Python > > user, I find that Python documentation is all over the usability map - some > > great, some

Re: Survey: improving the Python std lib docs

2017-05-13 Thread Terry Reedy
On 5/13/2017 1:23 PM, jeanbigbo...@gmail.com wrote: Thank you for bringing up this important topic. As an occasional Python user, I find that Python documentation is all over the usability map - some great, some difficult. The Python docs have been at best a starting point. I usually need

Re: Survey: improving the Python std lib docs

2017-05-13 Thread Terry Reedy
On 5/12/2017 6:02 AM, Steve D'Aprano wrote: Here are a couple of suggestions for improving(?) the docs. What do you think? (They're not my ideas, the originated on Reddit.) (1) Table of functions/classes at the start of each module doc The only thing possibly 'new' here is 'each' versus

Re: Survey: improving the Python std lib docs

2017-05-13 Thread jeanbigboute
On Friday, May 12, 2017 at 3:02:58 AM UTC-7, Steve D'Aprano wrote: > One of the more controversial aspects of the Python ecosystem is the Python > docs. Some people love them, and some people hate them and describe them as > horrible. > > Here are a couple of suggestions for improving(?) the

Re: Survey: improving the Python std lib docs

2017-05-13 Thread dieter
Steve D'Aprano writes: > One of the more controversial aspects of the Python ecosystem is the Python > docs. Some people love them, and some people hate them and describe them as > horrible. > > Here are a couple of suggestions for improving(?) the docs. What do you >

Re: Survey: improving the Python std lib docs

2017-05-12 Thread Chris Angelico
On Sat, May 13, 2017 at 4:05 AM, wrote: > On Friday, May 12, 2017 at 3:02:58 AM UTC-7, Steve D'Aprano wrote: > >> (1) Table of functions/classes at the start of each module doc >> >> The docs for builtins starts with a table of built-in functions: >> >>

Re: Survey: improving the Python std lib docs

2017-05-12 Thread Ethan Furman
On 05/12/2017 03:02 AM, Steve D'Aprano wrote: Here are a couple of suggestions for improving(?) the docs. What do you think? (1) Table of functions/classes at the start of each module doc I like this idea. Even if I don't know the exact thing I am looking for I can usually get close from

Re: Survey: improving the Python std lib docs

2017-05-12 Thread jladasky
On Friday, May 12, 2017 at 3:02:58 AM UTC-7, Steve D'Aprano wrote: > (1) Table of functions/classes at the start of each module doc > > The docs for builtins starts with a table of built-in functions: > > https://docs.python.org/3/library/functions.html > > > Docs for other modules should do

Re: Survey: improving the Python std lib docs

2017-05-12 Thread Dan Sommers
On Fri, 12 May 2017 21:14:01 +1000, Chris Angelico wrote: > On Fri, May 12, 2017 at 8:02 PM, Steve D'Aprano > wrote: >> (2) The PHP documentation allows you to search for a term by typing it into >> the URL after the domain, e.g. to search for "split", go to: >> >>

Re: Survey: improving the Python std lib docs

2017-05-12 Thread Chris Angelico
On Fri, May 12, 2017 at 8:02 PM, Steve D'Aprano wrote: > (2) The PHP documentation allows you to search for a term by typing it into > the URL after the domain, e.g. to search for "split", go to: > > http://php.net/split > > > If you try the same thing with the Python

Survey: improving the Python std lib docs

2017-05-12 Thread Steve D'Aprano
One of the more controversial aspects of the Python ecosystem is the Python docs. Some people love them, and some people hate them and describe them as horrible. Here are a couple of suggestions for improving(?) the docs. What do you think? (They're not my ideas, the originated on Reddit.) (1)