gh-101100: Fix Sphinx warnings in argparse module

[hugovk]

Fix Sphinx warnings in the argparse tutorial and library reference, plus add some missing bits to optparse that are referred to from argparse.

Before

❯ touch ./Doc/howto/argparse.rst ./Doc/library/argparse.rst; make -C Doc html SPHINXERRORHANDLING=-n 2>&1 | grep "argparse.*WARNING" | tee >(wc -l)
Doc/howto/argparse.rst:14: WARNING: c:func reference target not found: getopt
Doc/howto/argparse.rst:140: WARNING: py:meth reference target not found: add_argument
Doc/howto/argparse.rst:146: WARNING: py:meth reference target not found: parse_args
Doc/howto/argparse.rst:257: WARNING: py:attr reference target not found: args.verbosity
Doc/howto/argparse.rst:298: WARNING: py:data reference target not found: args.verbose
Doc/howto/argparse.rst:672: WARNING: py:meth reference target not found: ArgumentParser.parse_args
Doc/howto/argparse.rst:699: WARNING: py:meth reference target not found: add_mutually_exclusive_group
Doc/library/argparse.rst:587: WARNING: py:func reference target not found: locale.getpreferredencoding(False)
Doc/library/argparse.rst:1149: WARNING: py:exc reference target not found: ArgumentTypeError
Doc/library/argparse.rst:1191: WARNING: py:exc reference target not found: FileNotFound
Doc/library/argparse.rst:1445: WARNING: py:meth reference target not found: add_argument
Doc/library/argparse.rst:1718: WARNING: py:meth reference target not found: ArgumentParser.add_parser
Doc/library/argparse.rst:1788: WARNING: py:meth reference target not found: add_parser
Doc/library/argparse.rst:2159: WARNING: py:meth reference target not found: parse_known_args
Doc/library/argparse.rst:2288: WARNING: py:class reference target not found: optparse.Values
Doc/library/argparse.rst:2288: WARNING: py:exc reference target not found: optparse.OptionError
Doc/library/argparse.rst:2288: WARNING: py:exc reference target not found: optparse.OptionValueError
Doc/library/argparse.rst:2288: WARNING: py:exc reference target not found: ArgumentError
      18

After

I'm not sure how to fix these:

Doc/library/argparse.rst:1718: WARNING: py:meth reference target not found: ArgumentParser.add_parser
Doc/library/argparse.rst:1788: WARNING: py:meth reference target not found: add_parser

add_parser is a method of the _SubParsersAction class. Any ideas? Use the ! to silence them?

cpython/Lib/argparse.py

Line 1184 in de18267

def add_parser(self, name, **kwargs):

• Issue: Fix all Sphinx reference warnings in the documentation #101100

[encukou]

Use the ! to silence them?

IMO, generally that should be the last-resort. The goal is improving documentation, not getting rid of warnings. IMO, this warning is useful -- add_parser should be documented and mentions of it should generally be links.

But here, the current documentation is a sentence in ArgumentParser.add_subparsers() docs:

This object has a single method, add_parser(), which takes a command name and any ArgumentParser constructor arguments, and returns an ArgumentParser object that can be modified as usual.

And I guess that's fine in this case. It's in the same section as the would-be links to add_parser, so silencing them sounds OK in this particular case. The downside is that nothing outside this section (incl. third-party Intersphinx users) needs to link to ArgumentParser.add_subparsers instead.

If the class was bigger, and it would be clearer to use a concrete name rather than “special action object”, we'd want to document it. And perhaps even rename it in code to remove the underscore (or introduce a public superclass). Public names for helper classes are useful for typing, if nothing else.

[pradyunsg]

The option that I prefer would be to change the add_parser links/missing references into a regular inline code in this PR, and then document the add_parser method in a follow up. The alternative is documenting the add_parser method or reworking the API of the module around the subparser within this PR -- which is doing multiple things in a single PR and adding to the scope of the PR.

That said, I'm not opposed to having just the add_parser method get documented in this PR -- it's just that I don't see a direct/obvious way to document that, and figuring the details of that out is reasonable to defer to a follow up change IMO.

[ezio-melotti]

ISTM that in order to have a proper link for add_parser, we would have to add both the _SubParsersAction class and the add_parser method under it. Doing so will end up adding more churn and making the docs more confusing, unless there is a way to e.g. hide the class and only document the method (and even in that case it might not be worth the trouble).

Furthermore this method is only relevant while working with subparser, so if a link is needed, linking to the add_subparsers method or the "Sub-commands" sections are both acceptable solutions.

IOW, using ! is fine with me.

On an unrelated note, add_parser seems to support an additional aliases argument, that is mentioned below, but not included in the list of arguments (this should probably be addressed in a separate PR).

[CAM-Gerlach]

Sorry for the very long delay finally finishing this; we had some severe weather and I wanted to give it another round of thought.

ArgumentParser.add_parser is only used once, likely by mistake, as it is clearly incorrect and potentially misleading given add_parser is a method of the special subparsers object (_SubParsersAction), not ArgumentParser. Therefore, the one instance of it should at least be changed to just add_parser like the rest, for this PR at least.

As for add_parser itself, given it is referenced a number of times throughout the docs, we should explicitly (even if briefly) formally document it in some form, I would suggest just as a standalone method (prefixed with the class name), since you can document a method, attribute, etc. standalone without having to actually document the class by including the class prefix in the directive, like the Option attributes in these optparse docs currently do.

If @hugovk and/or people prefer, that could be addressed in a separate followup PR by Hugo or myself (either together or separately from properly documenting the Option/Values classes, if we also choose to do that separately from here) and just leave the valid warnings until then (i.e. don't remove Doc/library/argparse.rst from the ignore list just yet).

[CAM-Gerlach]

This technically means that the ref label above is pointing to the currentmodule directive as its target, rather than the paragraph. however, it should point to the top-level heading instead, so moving _argparse-tutorial: to right above the Argparse Tutorial heading will fix it. It won't affect backward compat as existing referents will still point to this page (except the top, as intended, rather than slightly down), while now allowing new referants to automatically use the document title if desired.

[CAM-Gerlach]

IMO, generally that should be the last-resort. The goal is improving documentation, not getting rid of warnings. IMO, this warning is useful -- add_parser should be documented and mentions of it should generally be links.

💯

The option that I prefer would be to change the add_parser links/missing references into a regular inline code in this PR, and then document the add_parser method in a follow up.

As illustrated below, it seems to be relatively straightforward to just add this as a standalone method without documenting the class. That said, if people prefer deferring documenting it, as well as possibly the two optparse classes I highlight above, to one or more followup PRs that that's totally fine too of course.

If we do defer it, though, we shouldn't silence the legitimate warnings, as they are genuine reminders of missing documentation—arguably among the most important and valuable here, as missing docs is a lot more meaningful to readers than one object name not being a link, and harder for other tooling to spot than just a typo in a ref target. (And at the very least, if we did, the way to do so would be just adding a ! to de-resolve the reference, rather than converting it to a whole different type with different semantics and output formatting.)

ISTM that in order to have a proper link for add_parser, we would have to add both the _SubParsersAction class and the add_parser method under it. Doing so will end up adding more churn and making the docs more confusing, unless there is a way to e.g. hide the class and only document the method (and even in that case it might not be worth the trouble).

There's actually no need to explicitly document the _SubParsersAction class; you can just add a standalone method with the class prefixed, just like the the Option attributes are prior to this PR, without the class being separately documented. E.g.:

.. method:: _SubParsersAction.add_parser(name, **kwargs)

   Description...

Furthermore this method is only relevant while working with subparser, so if a link is needed, linking to the add_subparsers method or the "Sub-commands" sections are both acceptable solutions.

Right, but the method is referenced a decent number of places, particularly in examples, and it would mean the method itself couldn't be linked, you'd have to manually link to the section which is more work for writers and somewhat klunky for readers. It also means the method won't show up in searches or in the index. Since it is in fact quite straightforward to add the standalone method (and document the additional undocumented aliases argument, as desired) without documenting the class, it seems reasonable to just properly document the method directly instead (either in this PR, or perhaps more pragmatically in a follow-up where we can discuss this further).

[hugovk]

Thanks all for the reviews! I changed both :meth:`~ArgumentParser.add_parser` and :meth:`add_parser` to :meth:`!add_parser`

If @hugovk and/or people prefer, that could be addressed in a separate followup PR by Hugo or myself (either together or separately from properly documenting the Option/Values classes, if we also choose to do that separately from here) and just leave the valid warnings until then (i.e. don't remove Doc/library/argparse.rst from the ignore list just yet).

I included your Option/Values suggestions here. Fine by me if you'd like to open a followup to document add_parser as you suggest 👍

[CAM-Gerlach]

As mentioned previously, I strongly feel we shouldn't silence valid warnings just to quiet a linter when they are legitimate reminders of missing documentation—arguably among the most important and valuable here, as missing docs is a lot more meaningful to readers than one object name not being a link, and harder for other tooling to spot than just a typo in a ref target. Furthermore, it means these links will automatically start working when we add the reference docs, without having to (remember to) manually search for and remove the !. it makes it easy to spot the instances that need to be updated (or in most cases, they just start working automagically when its fixed), without needing to remember to do a manual search.

Therefore, given the aforementioned potential obstacles to documenting this were cleared up, I suggest we leave this valid warning until fixed in the aforementioned followup (or we decide what else to do with it there).

[hugovk]

@CAM-Gerlach We're in no rush to get this one merged. Would you like to make the followup suggestions as a PR to my branch? https://github.com/hugovk/cpython/tree/docs-warnings-argparse

Then I can merge it and it'll update this PR :)

[hugovk]

At PyCon sprints: we decided to use the nitpick_ignore approach.

[CAM-Gerlach]

LGTM now, thanks @hugovk !

[miss-islington]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[miss-islington]

Sorry @hugovk, I had trouble checking out the 3.11 backport branch.
Please retry by removing and re-adding the "needs backport to 3.11" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 79ae019164eeb6b94118bc17bc1e937405684c75 3.11

[miss-islington]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[miss-islington]

Sorry, @hugovk, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 79ae019164eeb6b94118bc17bc1e937405684c75 3.11

[bedevere-bot]

GH-103803 is a backport of this pull request to the 3.11 branch.