Update documentation to reflect changes in --install-option functionality

[douglowe]

Recently a couple of users (including me) have tried to use the --install-option flag to pass --prefix flag information to pip: #9435. This isn't allowed anymore, but is still used as an example of how to use the --install-option flag in the documentation.

I would recommend correcting the example given in the 'per-requirement overrides' section, to remove the use of the --prefix flag: https://pip.pypa.io/en/stable/reference/pip_install/#per-requirement-overrides
I think it would also be useful to describe in this section which options are explicitly not allowed to be passed via the --install-option flag, and why (as mentioned in this comment: #9435 (comment)). Including this information would help users understand better what can be done with this flag.

I wonder also if the text describing the use of the --install-option flag needs some adjustment:
https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-install-option
This uses '--install-scripts' as the example flag being passed (which doesn't exist as far as I can see?). It would be better to use an existing option (such as --no-compile). This paragraph also mentions having to pass absolute paths for options - is this a redundant warning now that options such as --prefix are not allowed, or are there still some options requiring paths which are allowed?

[uranusjr]

--install-scripts is a setuptools option to install scripts to an alternative location, I believe still present. But this is indeed not a good example because pip really shouldn’t allow such user customisation (they mess up later pip list and pip uninstall calls). We should probably change it to something like --install-options=-O (the -O flag enables compile-time optimisation for extension modules).