--extra-index-url option documentation should have warning about "dependency confusion"

[Marcono1234]

What's the problem this feature will solve?

Currently the documentation for the --extra-index-url option does not warn about "dependency confusion", only the corresponding example contains a warning (added by #9647).

However, it is likely that users will miss that warning because they might not look at the examples section.

Describe the solution you'd like

In addition to the existing warning on the example, the documentation for the --extra-index-url option itself should also have a warning because that is most likely where users would first look for such a warning.

Alternative Solutions

-

Additional context

Not sure how easy it would be to implement this since the documentation for the options (including --extra-index-url) seems to be generated dynamically and might not support an RST warning box. Though at the very least a plaintext warning would be helpful as well. I assume in that case the warning would also be shown in the command line help, which would be useful too.

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[pfmoore]

A PR with proposed wording would be welcome.

[Kaushik-Iyer]

Should I try to work on this? Do we just need to change documentation text from pip_install.rst?

[Marcono1234]

Should I try to work on this? Do we just need to change documentation text from pip_install.rst?

I think that won't work because as mentioned above the documentation for these options does not seem to be part of pip_install.rst but seems to be generated dynamically (from cmdoptions.py?). But I might be wrong.