GH-124478: Cleanup argparse documentation

[savannahostrowski]

This PR:

1. Removes duplicative examples that are fairly basic and sufficiently covered in the tutorial
2. Removes the quick reference tables, as removing duplicative examples moves the reference docs for ArgumentParser and add_argument much higher up the page. I don't think this is terribly necessary anymore.
3. Move the upgrading to optparse guide to a separate page. Since optparse has been deprecated since 3.2, this is probably a minimally viewed part of the main argparse docs, so I think it's fair to have it on a separate page.
4. Consolidates some examples
5. Updates terminology (e.g., sub-command -> subcommand) for consistency.

Please let me know if there are other best practices we consistently use in other documentation areas but lack here. I'm happy to incorporate them here so we can get these documents feeling fresh!

(As a note, I tried to be somewhat conservative here as I do think many of the examples are 1) valuable for new users and 2) too advanced to add to the tutorial in its current form)

• Issue: Review and simplify argparse docs #124478

[JelleZijlstra]

I looked at the preview https://cpython-previews--124877.org.readthedocs.build/en/124877/library/argparse.html#module-argparse and skimmed the entire doc. Below are some things I noticed. None are new to this PR, so feel free to ignore them and I can file a separate PR with those cleanups.

• It's distracting that the first few paragraphs link :mod:`argparse` 4 times, and it just links back to the top of the page. Would recommend suppressing those links with :mod:`!argparse`.
• RawTextHelpFormatter description says "new lines"; I think it's normally spelled "newlines".
• "ArgumentParser uses filesystem encoding and error handler to read the file containing arguments." this sentence reads oddly, maybe needs a "the"
• "the action default will not over write it" -> I think "overwrite" is one word
• I might remove the parser.add_argument('source_file', type=open) example. It doesn't make it easy to properly close the file, and as the text says later, FileNotFoundError would not be handled nicely.
• FileType is formatted inconsistently in the paragraph that starts Even [FileType](https://cpython-previews--124877.org.readthedocs.build/en/124877/library/argparse.html#argparse.FileType) has its limitations for use with the type keyword.
• The text after "class argparse.Action" should be indented by another level.
• The docs for parse_known_intermixed_args are not properly indented.

[savannahostrowski]

Thanks so much for such a thorough review, @JelleZijlstra. I think I can incorporate your feedback in this PR. I'll revisit this tomorrow evening.

[willingc]

Lovely work @savannahostrowski. Thank you!

[savannahostrowski]

@JelleZijlstra, I applied all of your suggestions. I also found formatting inconsistencies in taking another pass related to indentation and style.

[miss-islington-app]

Thanks @savannahostrowski for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @savannahostrowski and @JelleZijlstra, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 37228bd16e3ef97d32da08848552f7ef016d68ab 3.13

[miss-islington-app]

Sorry, @savannahostrowski and @JelleZijlstra, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 37228bd16e3ef97d32da08848552f7ef016d68ab 3.12

[bedevere-app]

GH-125162 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-125164 is a backport of this pull request to the 3.12 branch.