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.

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.

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.:

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).

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 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 :)

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

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

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

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

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

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