docs: document some environment variables (#2077)
This is so they're more discoverable for both developers and users.
diff --git a/docs/sphinx/environment-variables.md b/docs/sphinx/environment-variables.md
new file mode 100644
index 0000000..2a00529
--- /dev/null
+++ b/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.
+:::
diff --git a/docs/sphinx/index.md b/docs/sphinx/index.md
index 13cfa56..8405eac 100644
--- a/docs/sphinx/index.md
+++ b/docs/sphinx/index.md
@@ -66,6 +66,7 @@
support
Changelog <changelog>
api/index
+environment-variables
glossary
genindex
```
diff --git a/python/private/pypi/attrs.bzl b/python/private/pypi/attrs.bzl
index 79ffea5..c6132cb 100644
--- a/python/private/pypi/attrs.bzl
+++ b/python/private/pypi/attrs.bzl
@@ -154,7 +154,7 @@
"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 @@
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
