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