Improve docs for --root-user-action option

[Mr-Pepe]

#11201 was too verbose, so this change just adds a note to the warning message itself and shows allowed values for the option when using pip install --help. The warning message now contains all information from the proposed alternative in the rejected PR but is easier to discover.

Closes #11179.

[pfmoore]

I'm not actually sure we want to make the option more discoverable. After all, we strongly recommend not using it, so it seems perfectly reasonable to me to require anyone who wants this option to have to do a bit of research to discover it. This isn't just "security by obscurity" - the hope is that by doing the research, the user will be exposed to the arguments against what they are trying to do and discussions of alternative approaches.

[Mr-Pepe]

I see where you are coming from but doing a quick search of "pip as root user" yields this as the first result, with the most upvoted answer just saying to use --root-user-action. I personally think it's okay to let the user know that they are doing something risky (like sudo giving the "With great power comes great responsibility" lecture on first usage) but also give them clear instructions for when they know what they are doing. Maybe pip's warning could be clearer about the consequences of "conflicting behavior with the system package manager", which is basically "you might brick your system". If someone takes that risk without doing basic research first, they'd probably also just use the first answer on Stackoverflow.

[Mr-Pepe]

Trying to unblock this PR. Feel free to close it if the proposed changes are fundamentally not desired.

[Mr-Pepe]

Python 3.9 on MacOS failed but I don't know how what I did could have triggered that and I don't have a MacBook to reproduce the error locally. Is that test flaky? Please let me know if there is anything I can do.

[uranusjr]

I reran and it fixed itself. Just a hiccup in CI, it seems.

[Mr-Pepe]

Just curious, what's missing to get this merged and out of my list of open pull requests? 😋

[Mr-Pepe]

I have rebased the branch one last time and will close this PR at some point in a few weeks if nothing happens.