Merge pull request #12576 from luismedel/8044-docs-envvars

Display env vars for pip options in docs

Author: pfmoore

docs/pip_sphinxext.py

@@ -14,9 +14,22 @@
 
 from pip._internal.cli import cmdoptions
 from pip._internal.commands import commands_dict, create_command
+from pip._internal.configuration import _normalize_name
 from pip._internal.req.req_file import SUPPORTED_OPTIONS
 
 
+def convert_cli_option_to_envvar(opt_name: str) -> str:
+    undashed_opt_name = _normalize_name(opt_name)
+    normalized_opt_name = undashed_opt_name.upper().replace("-", "_")
+    return f"PIP_{normalized_opt_name}"
+
+
+def convert_cli_opt_names_to_envvars(original_cli_opt_names: List[str]) -> List[str]:
+    return [
+        convert_cli_option_to_envvar(opt_name) for opt_name in original_cli_opt_names
+    ]
+
+
 class PipNewsInclude(rst.Directive):
     required_arguments = 1
 
@@ -130,7 +143,18 @@ def _format_option(
         opt_help = option.help.replace("%default", str(option.default))
         # fix paths with sys.prefix
         opt_help = opt_help.replace(sys.prefix, "<sys.prefix>")
-        return [bookmark_line, "", line, "", "    " + opt_help, ""]
+        env_var_names = convert_cli_opt_names_to_envvars(option._long_opts)
+        env_var_names_src = ", ".join(f"``{env_var}``" for env_var in env_var_names)
+        return [
+            bookmark_line,
+            "",
+            line,
+            "",
+            f"    {opt_help}",
+            "",
+            f"    (environment variable: {env_var_names_src})",
+            "",
+        ]
 
     def _format_options(
         self, options: Iterable[optparse.Option], cmd_name: Optional[str] = None

news/12576.doc.rst

@@ -0,0 +1 @@
+Document the environment variables that correspond with CLI options.