[bazel] add documentation for rules/nonhermetic.bzl

Signed-off-by: Gary Guo <gary.guo@lowrisc.org>
(cherry picked from commit 73d55bc)

Author: nbdd0121

rules/nonhermetic.bzl

@@ -14,6 +14,24 @@ NONHERMETIC_BINS = [
     "updatemem",
 ]
 
+"""Variables that describe non-hermetic parts of the environment.
+
+This repository provides 3 variables:
+    - `ENV`
+        - Dict of environment variables that may be needed for running non-hermetic tools.
+          Currently this only include those needed by Vivado.
+    - `HOME`
+        - Home directory of the user that invokes Bazel.
+          Currently this is used by hsmtool to access user's Google Cloud credentials.
+    - `BIN_PATHS`
+        - Map from a non-hermetic tool to the part of `$PATH` that contains it.
+          This allows actions to use a subset of `$PATH` when invoking the tool,
+          as `$PATH` may contain many unrelated tools.
+
+Together, these variables attempt to expose the least amount of environment information
+to Bazel rules as possible, thus improves reproducibility and cacheability.
+"""
+
 def _nonhermetic_repo_impl(rctx):
     env = "\n".join(["    \"{}\": \"{}\",".format(v, rctx.os.environ.get(v, "")) for v in NONHERMETIC_ENV_VARS])
     home = rctx.os.environ.get("HOME", "")