docs: document some environment variables (#2077)

This is so they're more discoverable for both developers and users.

Author: rickeylev

docs/sphinx/environment-variables.md

@@ -0,0 +1,48 @@
+# Environment Variables
+
+:::{envvar} RULES_PYTHON_REPO_DEBUG
+
+When `1`, repository rules will print debug information about what they're
+doing. This is mostly useful for development to debug errors.
+:::
+
+:::{envvar} RULES_PYTHON_REPO_DEBUG_VERBOSITY
+
+Determines the verbosity of logging output for repo rules. Valid values:
+
+* `DEBUG`
+* `INFO`
+* `TRACE`
+:::
+
+:::{envvar} RULES_PYTHON_PIP_ISOLATED
+
+Determines if `--isolated` is used with pip.
+
+Valid values:
+* `0` and `false` mean to not use isolated mode
+* Other non-empty values mean to use isolated mode.
+:::
+
+:::{envvar} RULES_PYTHON_BZLMOD_DEBUG
+
+When `1`, bzlmod extensions will print debug information about what they're
+doing. This is mostly useful for development to debug errors.
+:::
+
+:::{envvar} RULES_PYTHON_ENABLE_PYSTAR
+
+When `1`, the rules_python Starlark implementation of the core rules is used
+instead of the Bazel-builtin rules. Note this requires Bazel 7+.
+:::
+
+:::{envvar} RULES_PYTHON_BOOTSTRAP_VERBOSE
+
+When `1`, debug information about bootstrapping of a program is printed to
+stderr.
+:::
+
+:::{envvar} VERBOSE_COVERAGE
+
+When `1`, debug information about coverage behavior is printed to stderr.
+:::

docs/sphinx/index.md

@@ -66,6 +66,7 @@ Contributing <contributing>
 support
 Changelog <changelog>
 api/index
+environment-variables
 glossary
 genindex
 ```

python/private/pypi/attrs.bzl

@@ -154,7 +154,7 @@ or empty in the environment), if `"VARNAME"` is listed in the
     "isolated": attr.bool(
         doc = """\
 Whether or not to pass the [--isolated](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-isolated) flag to
-the underlying pip command. Alternatively, the `RULES_PYTHON_PIP_ISOLATED` environment variable can be used
+the underlying pip command. Alternatively, the {envvar}`RULES_PYTHON_PIP_ISOLATED` environment variable can be used
 to control this flag.
 """,
         default = True,
@@ -185,13 +185,10 @@ python_interpreter. An example value: "@python3_x86_64-unknown-linux-gnu//:pytho
         doc = """\
 If True, suppress printing stdout and stderr output to the terminal.
 
-If you would like to get more diagnostic output, please use:
-
-    RULES_PYTHON_REPO_DEBUG=1
-
+If you would like to get more diagnostic output, set
+{envvar}`RULES_PYTHON_REPO_DEBUG=1 <RULES_PYTHON_REPO_DEBUG>`
 or
-
-    RULES_PYTHON_REPO_DEBUG_VERBOSITY=<INFO|DEBUG|TRACE>
+{envvar}`RULES_PYTHON_REPO_DEBUG_VERBOSITY=<INFO|DEBUG|TRACE> <RULES_PYTHON_REPO_DEBUG_VERBOSITY>`
 """,
     ),
     # 600 is documented as default here: https://docs.bazel.build/versions/master/skylark/lib/repository_ctx.html#execute