Document the environment variables which influence pip's behaviour

[wimglenn]

The Python docs detail exactly what environment variables are usable and how they influence python's behavior: https://docs.python.org/3/using/cmdline.html?highlight=pythonpath#environment-variables

A similar section for pip's docs would be very helpful. The environment configuration section is not as useful: https://pip.pypa.io/en/stable/user_guide/#environment-variables

It just says to use PIP_<UPPER_LONG_NAME> but it's pretty much guesswork what UPPER_LONG_NAME are possible here, if you don't already have good familiarity with all the options and subcommands of the CLI.

The docs then go on to give an example of export PIP_DEFAULT_TIMEOUT=60 being equivalent to pip --default-timeout=60, but nothing in pip --help mentions --default-timeout (and the configuration section itself seems to be the only docs reference about it), so how would a user discover that in the first place?

[pralkarz]

Is there a way to dynamically alter that section so it gets updated based on the # options # section?

pip/src/pip/_internal/cli/cmdoptions.py

Lines 141 to 143 in b55ec00

	###########
	# options #
	###########

I'd tackle this issue, but it would be a waste of time to type it out manually if a more optimal solution was available, so I'm open to any advice! 😄

[uranusjr]

There is always a way with Sphinx plugins. Whether it’s easy or not, is another question (that I don’t know the answer of).

[pradyunsg]

We have a bunch of logic already, for preventing such duplication with Sphinx plugins. See:

pip/docs/pip_sphinxext.py

Line 169 in b55ec00

class PipCommandOptions(PipOptions):

This is worth exploring, but as @uranusjr said -- it's not easy to know whether this is worth doing yet.

[pralkarz]

All right, then I'm going to wait until there's a consensus whether this is worth implementing or not. Another solution would be to simply link the documentation page for pip's command line options along with the current explanation on the feature, however there are separate URLs for every command, so that might not be suitable/optimal.

[abe-101]

The docs then go on to give an example of export PIP_DEFAULT_TIMEOUT=60 being equivalent to pip --default-timeout=60, but nothing in pip --help mentions --default-timeout (and the configuration section itself seems to be the only docs reference about it), so how would a user discover that in the first place?

Is it possible that is a mistake in the documentation and it is meant to be "export PIP_TIMEOUT=60 being equivalent to pip --timeout=60"?

There seems to be a pull request fixing this #9697