clarified docs for env-vars and config files

[zerothi]

More links between sections are added.
It should bring all documentation together
in a more coherent manner.

The Environemnt variables section has been
cleaned.
Now there are not 3 random examples which
might have confused users to only suspect that those 3 examples where the only available ones.
Now this section clarifies how any CLI-option
is specified through an env var, and clarifies
that the shell example, is an example.

[zerothi]

This was born out of the discussion in #13043, hence the branch reference.

[ichard26]

Sorry for long delay. Improvements to pip's documentation are appreciated. I like where this is going, but I do think this needs some tweaking.

[ichard26]

Thank you for your patience!

[zerothi]

Great! Looks complete to me!

[sbidoul]

Does this part work as is on Windows, or should this part use tabs?

[pfmoore]

Windows doesn't support the ENV_VAR=value command syntax at all. The examples would need to use

set PIP_VERBOSE=3
set PIP_CACHE_DIR=C:\Temp
pip ...

(CMD syntax), or

$env:PIP_VERBOSE=3
$env:PIP_CACHE_DIR="C:\Temp"
pip ...

(Powershell syntax). I'm not sure whether our Windows examples use CMD or Powershell - the ones I could find work the same in both shells. There's also the complication that if you want multiple examples, you need to unset the variables from the previous example on Windows - again because the ENV=value cmd syntax doesn't exist.

To be honest, giving explicit examples of shell syntax might be more confusing than helpful for beginners, and advanced users can probably work out the shell syntax based on a description.

One possible compromise would be to use the env command - env PIP_VERBOSE=3 PIP_CACHE_DIR=/home/user/tmp pip .... The env command doesn't exist by default on Windows, but it's possible to find ports of it. It's not ideal, but it's the only real way of getting a proper Windows equivalent of the Unix examples given (and it has the advantage that it works fine on Unix as well 🙂)

[zerothi]

Agree on @pfmoore views, there are many places were there is no differentiation between unix/powershell/command.. So I think it can go directly in.

[pfmoore]

Hang on, I was not saying this could be left as it is. Quite the opposite, I was saying that the docs need to be platform-neutral, but that's near-impossible to do in this case, so we should stick with describing the behaviour in the text, without trying to give examples.

[zerothi]

but, what about the previous documentation PIP_TIMEOUT=60, should that hold us back know?

See other maintainer review feedback.

[zerothi]

So what is missing here, could this be helped through?

[ichard26]

So what is missing here, could this be helped through?

TBH, I don't know. You'll have to address Paul's feedback about removing the platform specific stuff: #13050 (comment).

If you're interested in filing a new PR, you are welcome to, although I understand if you aren't interested. I'll close this out now since it has been a while without any activity (and this isn't close to be mergeable, unfortunately) but let us know if you want to pick this up.