classification
Title: argparse doc introduction is inappropriately targeted
Type: Stage: patch review
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BGuo1, Daniel Stone, cheryl.sabella, docs@python, martin.panter, paul.j3
Priority: normal Keywords: patch

Created on 2016-03-21 12:11 by Daniel Stone, last changed 2017-06-04 21:10 by cheryl.sabella.

Files
File name Uploaded Description Edit
bguo.patch BGuo1, 2016-03-23 04:18 review
Messages (5)
msg262121 - (view) Author: Daniel Stone (Daniel Stone) Date: 2016-03-21 12:11
The argparse documentation starts off, after a couple of sentences, by spending several paragraphs (and a couple of sentences) explaining this gem:
import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
                   help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                   const=sum, default=max,
                   help='sum the integers (default: find the max)')

args = parser.parse_args()
print(args.accumulate(args.integers))


While it is undoubtedly impressive, that a sidebar had to be inserted suggesting people in fact refer to other documentation, suggests it may be inappropriate. As an introduction, it is not particularly approachable (especially if you don't catch the nuance of assigning functions to accumulate), and is probably not going to serve the immediate needs of a lot of the audience: the people who click on the first hit for 'python argparse'.

I would suggest relegating this example elsewhere in the documentation, with a much more straightforward/realistic example to lead the documentation.
msg262238 - (view) Author: Brian Guo (BGuo1) * Date: 2016-03-23 04:18
Hi,

I agree with your observation about the unnecessarily complicated documentation. I feel that there is not a real necessity to include an example that uses (metavar='N', nargs='+') or even (const='sum', default='max') inside the parameters of the add_argument method, as they are not explained in the beginning section and simply appear to contribute clutter.

For this reason, I have written an easier document to understand (still keeping the sidebar tutorial, because it is a helpful reference). I use instead a method that accepts a string and returns the first letter. I hope this will add to the clarity of the document.
msg262311 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2016-03-23 21:31
By text and location the sidebar does not apply specifically to this example.  It applies to the whole page, 'This page contains the API reference information.'

Documentation for argparse is indeed a problem - both because of its complexity and how it is used.  Many other reference modules focus on the classes and their methods.  This is organized about one class, the parser object, and a couple of its methods.  It's really more of an advanced user's tutorial, making most sense to users who already have use optparse and getopt.  For them that initial example is appropriate, selling them on the power of this parser.

For beginners I'd focus on the tutorial and its examples.  Example or not this reference section can be overwhelming to beginning Python users.
msg289572 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-03-14 08:22
The patch looks unfinished. I left some narrow nit-picky review comments, but I haven’t really thought about the problem from a high level.
msg295144 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-06-04 21:10
If it helps at all, I first learned about argparse a few weeks ago.  I first went to the doc page and then immediately went to the tutorial, as suggested.  I didn't find it difficult or off-putting at all.  In fact, I loved that there was a tutorial that it explained it perfectly for my level as a newbie.  I've referenced the doc page a few times since, but I haven't read it from beginning to end like I did to learn the str functions, for example.  I think the doc page should be more advanced for people who need to know it's full power (as it is now) and the tutorial can serve newbies (as it does now).
History
Date User Action Args
2017-06-04 21:10:28cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg295144
2017-03-14 08:22:46martin.pantersetversions: + Python 2.7, Python 3.5, Python 3.6, Python 3.7
nosy: + martin.panter

messages: + msg289572

stage: patch review
2016-03-23 21:31:41paul.j3setnosy: + paul.j3
messages: + msg262311
2016-03-23 04:18:27BGuo1setfiles: + bguo.patch

nosy: + BGuo1
messages: + msg262238

keywords: + patch
2016-03-21 12:11:34Daniel Stonecreate