classification
Title: give more meaningful argument names in argparse documentation
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: adam.woodbeck, bethard, chris.jerdonek, dlam, docs@python, eric.araujo, ezio.melotti, georg.brandl, groodt, lonetwin, marcs, sandro.tosi, tshepang, westley.martinez
Priority: normal Keywords: easy, patch

Created on 2011-02-10 15:48 by bethard, last changed 2019-04-26 17:44 by BreamoreBoy.

Files
File name Uploaded Description Edit
argparse_simple_example.diff groodt, 2012-07-07 10:13 review
issue11165-doc-fix-up-to-section-15.4.4.diff dlam, 2012-07-09 06:11 review
1176_minor_edits.diff groodt, 2012-07-09 19:53 review
issue11176.patch dlam, 2012-08-28 09:33
Messages (19)
msg128302 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2011-02-10 15:48
Suggestion from a personal email:

I personally am not keen on the foo/bar/baz examples. I
know that you're trying to be generic but IMO it would be much easier to
understand if you used meaningful names. Also, I think that the very
first example you give (which does use meaningful names:-) is too
clever. I'd suggest using something simpler: in fact I'd use exactly the
same example that optparse uses (--file && --quiet) since that is easy
to understand and relate to straight away, and maybe add a --line option
that takes a list of ints (ostensibly line numbers of lines to extract
from the file) if you want to show that argparse leaves optparse in the
dust. And you can always show how to get actual file objects later on.
msg128355 - (view) Author: Westley Martínez (westley.martinez) * Date: 2011-02-11 00:23
I agree; it's too artsy. I'll see if I can come up with a relevant and clever alternative.
msg140679 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-19 16:04
Hi Westley!  Do you still have time to work on this?
msg140685 - (view) Author: Westley Martínez (westley.martinez) * Date: 2011-07-19 18:04
I worked on this some time ago; the problem was the size of the documentation, i.e. it was difficult to stay consistent.  Do I have time for this?  Yes, but I wouldn't get it done anytime soon, and the results could be anywhere from good to bad.  As it stands, the documentation is fairly good, so I don't think it's imperative to fix it.
msg140745 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-20 15:11
> I worked on this some time ago; the problem was the size of the
> documentation, i.e. it was difficult to stay consistent.
I think it’s okay to improve the docs one patch at a time, starting with the simple example referenced in the first message in this bug report, and gradually improving other sections.  Do you have a diff with your work, so that your efforts can serve as a base for someone else?

> Do I have time for this?  Yes, but I wouldn't get it done anytime
> soon, and the results could be anywhere from good to bad.
That’s why we do reviews :)  It’s okay if you don’t have time, I’m interested in working on this some time in the future.
msg164802 - (view) Author: Greg Roodt (groodt) * Date: 2012-07-07 10:13
Is this still an issue? If so, I've created a simpler first example as suggested below. 

If we decide these docs still need a bit more work, I can also continue to provide better examples than the "foo bar" ones.
msg165059 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-09 04:56
Yep, this is still open.  Thanks for the patch, I did a review (if you did not get a mail, follow the link in the list of files).
msg165068 - (view) Author: David Lam (dlam) * Date: 2012-07-09 06:11
haha wow, I was working on this bug too!  maybe we can work on the final patch together

I got through about 2/3's of the docs, so I thought it might help to upload what I got so far.  I basically just made stuff up so I'm totally winning to change anything (or everything)

I made a little effort to make the examples mildly amusing, since novelty sorta helps in retention.  So one of the recurring examples I used involves that of a pizza-making-program... hopefully this helps in some way!
msg165109 - (view) Author: Greg Roodt (groodt) * Date: 2012-07-09 19:02
Hi David

Ok, I like the idea of working on a solution together. I like your idea of
the pizza-making more than the current "foo bar" examples.

Should we collaborate outside of the bug tracker?

Greg

On 9 July 2012 07:11, David Lam <report@bugs.python.org> wrote:

>
> David Lam <d@dlam.me> added the comment:
>
> haha wow, I was working on this bug too!  maybe we can work on the final
> patch together
>
> I got through about 2/3's of the docs, so I thought it might help to
> upload what I got so far.  I basically just made stuff up so I'm totally
> winning to change anything (or everything)
>
> I made a little effort to make the examples mildly amusing, since novelty
> sorta helps in retention.  So one of the recurring examples I used involves
> that of a pizza-making-program... hopefully this helps in some way!
>
> ----------
> nosy: +dlam
> Added file:
> http://bugs.python.org/file26325/issue11165-doc-fix-up-to-section-15.4.4.diff
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue11176>
> _______________________________________
>
msg165115 - (view) Author: Greg Roodt (groodt) * Date: 2012-07-09 19:53
I've made the minor edits required after the review to my simplification of the first example.

David, perhaps we combine our efforts? Use my simple first example to explain the very basics, then continue the explanation with the pizza example?

Im happy either way, I quite like your example using the system dictionary.
msg165731 - (view) Author: David Lam (dlam) * Date: 2012-07-17 21:49
yup yup, go for it
msg166182 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2012-07-22 23:37
Thanks for working on this! I think keeping the first example as simple is possible is probably a good idea. And I didn't have time to read through the whole patch, but as far as I went, the pizza examples looked great.
msg169258 - (view) Author: David Lam (dlam) * Date: 2012-08-28 09:33
here's a patch that covers all but one of the foo/bar/baz examples

it also has fixes for the sample code near the beginning from the review Ezio did 

the one example I didn't do was the "Arguments containing -" part. I guess it felt like changing the names in that example would distract from what it was trying to illustrate there

Anyways, I tried to proofread it so hopefully it reads okay, enjoy enjoy ^^
msg177641 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-17 10:49
Also see this e-mail to docs@:

http://mail.python.org/pipermail/docs/2012-December/012028.html

> Subject: [docs] FOO and BAR
>
> Do you think it would be possible to write your documentation avoiding the silly usage of FOO and BAR everywhere? This is a very very old and boring joke, and does nothing to clarify what you are trying to clarify. If you could include real-world examples in your documentation, rather than "clever" programmer "jokes", learners such as myself would have far more respect for the good work you are obviously doing here.
>
> For example, the section on argparser is full of this sort of rubbish:
> argparse.ArgumentParser(description='A foo that bars')
>
> Under what circumstances would you ever put that in a program? Are you mad?
>
> Please take this into consideration.
msg179764 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-12 03:36
Issue 16933 improved the "choices" examples.
msg198350 - (view) Author: Westley Martínez (westley.martinez) * Date: 2013-09-24 02:55
I've skimmed through the patches.  Good job kids.  This is much better than it was before.  No more of that silly command-line calculator or the foobar nonsense that sounds drier than the POSIX standard.

Is there anything else that needs to be done?
msg199034 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-06 06:59
> Also see this e-mail to docs@:
> http://mail.python.org/pipermail/docs/2012-December/012028.html

No, please don't see this e-mail.  It's not worth it.  The poster clearly has no clue whatsoever about either a) common placeholders, or b) manners.

I don't want to claim that foo/bar/etc. are superior to a well-thought-out example (which takes time to come up with), but they are certainly better than no example at all.
msg220779 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-16 22:47
If we've got some meaningful changes can we please get them committed.  However I'd like to state that with over 4000 issues open we've got better things to do than change docs because somebody doesn't like the use of foo, bar and baz in examples.
msg229510 - (view) Author: Steve (lonetwin) Date: 2014-10-16 07:18
I came here to file a bug against the argparse documentation because reading through the documentation I didn't realize a good usecase for the `epilog` argument to the `ArgumentParser()` class until I started noticing that some commandline tools end with examples of usage.

I found this bug and so thought it would be better to just leave a comment here instead.

I glaced through the submitted patches and noticed that the pizza making example has `epilog="Remember: select a good combination to ensure maximum tastiness` ...which while good, still might not immediately convey the usefulness of the epilog parameter (just IMHO). I think, the example would be better served by something like:

>>> pizza_parser = argparse.ArgumentParser(
...     description='Make a pizza out of ingredients and toppings',
...     epilog="""Examples: Create a Python Lovers pizza using the command::
...     ./makepizz.py spam ham eggs
...     """)

Of course this example would then also require passing a formatter_class argument to handle the wrapping ...but in essence the point of my comment is that the examples might be more useful if a 'real-world' usage is demonstrated.
History
Date User Action Args
2019-04-26 17:44:59BreamoreBoysetnosy: - BreamoreBoy
2014-10-16 07:18:18lonetwinsetnosy: + lonetwin
messages: + msg229510
2014-06-16 22:47:06BreamoreBoysetnosy: + BreamoreBoy
messages: + msg220779
2013-10-06 06:59:11georg.brandlsetnosy: + georg.brandl
messages: + msg199034
2013-09-24 02:55:35westley.martinezsetmessages: + msg198350
2013-01-12 03:36:48chris.jerdoneksetmessages: + msg179764
2012-12-17 10:49:18chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg177641
2012-08-28 09:33:15dlamsetfiles: + issue11176.patch

messages: + msg169258
2012-07-22 23:37:07bethardsetmessages: + msg166182
2012-07-17 21:49:50dlamsetmessages: + msg165731
2012-07-09 19:53:23groodtsetfiles: + 1176_minor_edits.diff

messages: + msg165115
2012-07-09 19:02:46groodtsetmessages: + msg165109
2012-07-09 06:11:33dlamsetfiles: + issue11165-doc-fix-up-to-section-15.4.4.diff
nosy: + dlam
messages: + msg165068

2012-07-09 04:56:51eric.araujosetassignee: eric.araujo ->

messages: + msg165059
nosy: + ezio.melotti, sandro.tosi
2012-07-07 10:13:34groodtsetfiles: + argparse_simple_example.diff

nosy: + groodt
messages: + msg164802

keywords: + patch
2012-03-18 21:35:25tshepangsetnosy: + tshepang
2011-09-19 14:04:31marcssetnosy: + marcs
2011-08-31 03:03:58adam.woodbecksetnosy: + adam.woodbeck
2011-07-20 15:11:52eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg140745
2011-07-19 18:04:49westley.martinezsetmessages: + msg140685
2011-07-19 16:04:49eric.araujosetversions: + Python 2.7, Python 3.2
nosy: + eric.araujo

messages: + msg140679

keywords: + easy
2011-02-11 00:23:44westley.martinezsetnosy: + westley.martinez
messages: + msg128355
2011-02-10 15:48:55bethardcreate