clarified docs for env-vars and config files

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]>

docs/html/topics/configuration.md

@@ -2,11 +2,13 @@
 
 # Configuration
 
-pip allows a user to change its behaviour via 3 mechanisms:
+pip allows a user to change its behaviour via 3 mechanisms.
+These mechanisms are listed in order of priority, meaning that
+command line options has [preference](config-preference):
 
-- command line options
-- environment variables
-- configuration files
+1. command line options
+2. [environment variables](env-variables)
+3. [configuration files](config-file)
 
 This page explains how the configuration files and environment variables work,
 and how they are related to pip's various command line options.
@@ -28,7 +30,12 @@ pip has 3 "levels" of configuration files:
 - `user`: per-user configuration file.
 - `site`: per-environment configuration file; i.e. per-virtualenv.
 
-Additionally, environment variables can be specified which will override any of the above.
+```{note}
+Options specified through environment variables or command line options
+take precedence over configuration files.
+
+See the [preference section](config-preference) for more details.
+```
 
 ### Location
 
@@ -199,33 +206,38 @@ trusted-host =
 This enables users to add additional values in the order of entry for such
 command line arguments.
 
-## Environment Variables
+(env-variables)=
 
-pip's command line options can be set with environment variables using the
-format `PIP_<UPPER_LONG_NAME>` . Dashes (`-`) have to be replaced with
-underscores (`_`).
+## Environment Variables
 
-- `PIP_TIMEOUT=60` is the same as `--timeout=60`
-- ```
-  PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
-  ```
+All pip's command line options have equivalent environment variables,
+they can be specified using:
+```shell
+PIP_<UPPER_LONG_NAME>
+```
 
-  is the same as
+Options with dashes (`-`) have to be replaced with underscores (`_`).
 
-  ```
-  --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com
-  ```
+Examples:
 
-Repeatable options that do not take a value (such as `--verbose`) can be
-specified using the number of repetitions:
+```shell
+PIP_VERBOSE=3 PIP_CACHE_DIR=/home/user/tmp pip ...
+# is equivalent to
+pip ... -vvv --cache-dir=/home/user/tmp
+```
 
-- `PIP_VERBOSE=3` is the same as `pip install -vvv`
+All option values follows the same rules as for the [configuration files](config-file).
 
 ```{note}
 Environment variables set to an empty string (like with `export X=` on Unix) will **not** be treated as false.
 Use `no`, `false` or `0` instead.
+
+Consequently, boolean options prefixed with `--no-*` can be disabled by using
+truthy values, e.g. `PIP_NO_CACHE_DIR=true`.
 ```
 
+(config-preference)=
+
 ## Precedence / Override order
 
 Command line options override environment variables, which override the