clarified docs for env-vars and config files #13050
Conversation
|
This was born out of the discussion in #13043, hence the branch reference. |
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. Signed-off-by: Nick Papior <[email protected]>
Signed-off-by: Nick Papior <[email protected]>
zerothi
force-pushed
the
13043-docs-env-vars
branch
from
dc77343 to
627a1ae
Compare
Signed-off-by: Nick Papior <[email protected]>
ichard26
added
the
skip news
|
Great! Looks complete to me! |
| ```shell | ||
| PIP_VERBOSE=3 PIP_CACHE_DIR=/home/user/tmp pip ... | ||
| PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" pip ... | ||
| PIP_NO_DEPS=yes pip ... |
There was a problem hiding this comment.
Does this part work as is on Windows, or should this part use tabs?
There was a problem hiding this comment.
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 🙂)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
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.