[docs] argparse doc example not especially helpful
sandro.tosi at gmail.com
Thu Aug 11 02:53:42 CEST 2011
sorry for this very late reply.
Would you like to provide some code examples for your proposal? That
would help us a lot in improving the doc.
On Wed, Mar 16, 2011 at 07:39, Tyler J. Barth <tyler.j.barth at gmail.com> wrote:
> I propose an improvement to the documentation for argparse
> I posit that the example 15.4.1 is not immediately helpful for the majority
> of people coming to docs.python.org to figure out how to use argparse.
> Though the use of argparse features to effortlessly sum and max the input
> integers is clever (and demonstrates many advanced features), I think most
> people arriving on that page want to know how to do three things:
> -Read in a file ("input.txt")
> -Read in a boolean switch ("-bar", use bar mode or not)
> -Read in a value for a switch ("-foo 6", set variable foo to 6)
> Of course, by hunting through the rest of the documentation you can learn
> how to do all of these basic tasks and more (much, much more).
> The clever sum and max example doesn't help elucidate how to perform these
> simple parses, and by using advanced features actually confuses new users.
> "argparse" has much more power than most people need, and I think it is fair
> to say that it's power obscures how to do the most common tasks. However,
> because "optparse" is deprecated and we all probably want to discourage
> people from rolling their own argument parsers every time they make a new
> simple program, I think there is value in making the "common case" more
> prominent in the example.
> It would encourage adoption of argparse so that when users's programs
> eventually increase in complexity and they do want to expand functionality,
> they would have the full power of argparse at their disposal.
> In summary, my suggestion is:
> -Expand example 15.4.1 to include the most common use cases
> -Consider splitting the "clever" example into a different section to avoid
> confusing new users.
> Tyler Barth
> docs mailing list
> docs at python.org
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi
More information about the docs