Ok, here's what I think needs to go into the documentation here:
(1) Add a separate section to the argparse docs about '--'. Give examples like the ones in this issue, and show how '--' can solve them
(2) Cross-reference the section on '--' from nargs='?', nargs='*', nargs='+' and the "Arguments containing -" sections (and any other places where people are likely to run into the need for '--').
All of these changes should be on Doc/library/argparse.rst - I don't think we want to change the code at the moment.