[docs] [issue26602] argparse doc introduction is inappropriately targeted

[Daniel Stone]

New submission from Daniel Stone:

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.

----------
assignee: docs at python
components: Documentation
messages: 262121
nosy: Daniel Stone, docs at python
priority: normal
severity: normal
status: open
title: argparse doc introduction is inappropriately targeted

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue26602>
_______________________________________