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.

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.

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.

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.

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).