chore: improve formatting

py/defs.bzl

@@ -1,5 +1,38 @@
 """Re-implementations of [py_binary](https://bazel.build/reference/be/python#py_binary)
 and [py_test](https://bazel.build/reference/be/python#py_test)
+
+## Choosing the Python version
+
+The `python_version` attribute must refer to a python toolchain version
+which has been registered in the WORKSPACE or MODULE.bazel file.
+
+When using WORKSPACE, this may look like this:
+
+```starlark
+load("@rules_python//python:repositories.bzl", "py_repositories", "python_register_toolchains")
+
+python_register_toolchains(
+    name = "python_toolchain_3_8",
+    python_version = "3.8.12",
+    # setting set_python_version_constraint makes it so that only matches py_* rule  
+    # which has this exact version set in the `python_version` attribute.
+    set_python_version_constraint = True,
+)
+
+# It's important to register the default toolchain last it will match any py_* target. 
+python_register_toolchains(
+    name = "python_toolchain",
+    python_version = "3.9",
+)
+```
+
+Configuring for MODULE.bazel may look like this:
+
+```starlark
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.toolchain(python_version = "3.8.12", is_default = False)
+python.toolchain(python_version = "3.9", is_default = True)
+```
 """
 
 load("@aspect_bazel_lib//lib:utils.bzl", "propagate_common_rule_attributes")
@@ -59,17 +92,17 @@ def _py_binary_or_test(name, rule, srcs, main, deps = [], resolutions = {}, **kw
 def py_binary(name, srcs = [], main = None, **kwargs):
     """Wrapper macro for [`py_binary_rule`](#py_binary_rule).
 
-    Creates a virtualenv to constrain the interpreter and packages used at runtime.
-    Users can `bazel run [name].venv` to create the virtualenv, then use it in the editor or other tools.
+    Creates a (py_venv)[./venv.md] target to constrain the interpreter and packages used at runtime.
+    Users can `bazel run [name].venv` to create this virtualenv, then use it in the editor or other tools.
 
     Args:
         name: Name of the rule.
         srcs: Python source files.
         main: Entry point.
             Like rules_python, this is treated as a suffix of a file that should appear among the srcs.
-            If absent, then "[name].py" is tried. As a final fallback, if the srcs has a single file,
+            If absent, then `[name].py` is tried. As a final fallback, if the srcs has a single file,
             that is used as the main.
-        **kwargs: additional named parameters to the py_binary_rule.
+        **kwargs: additional named parameters to `py_binary_rule`.
     """
 
     # For a clearer DX when updating resolutions, the resolutions dict is "string" -> "label",

py/private/py_binary.bzl

@@ -141,39 +141,7 @@ _attrs = dict({
         mandatory = True,
     ),
     "python_version": attr.string(
-        doc = """Whether to build this target and its transitive deps for a specific python version.
-
-Note that setting this attribute alone will not be enough as the python toolchain for the desired version
-also needs to be registered in the WORKSPACE or MODULE.bazel file.
-
-When using WORKSPACE, this may look like this,
-
-```
-load("@rules_python//python:repositories.bzl", "py_repositories", "python_register_toolchains")
-
-python_register_toolchains(
-    name = "python_toolchain_3_8",
-    python_version = "3.8.12",
-    # setting set_python_version_constraint makes it so that only matches py_* rule  
-    # which has this exact version set in the `python_version` attribute.
-    set_python_version_constraint = True,
-)
-
-# It's important to register the default toolchain last it will match any py_* target. 
-python_register_toolchains(
-    name = "python_toolchain",
-    python_version = "3.9",
-)
-```
-
-Configuring for MODULE.bazel may look like this:
-
-```
-python = use_extension("@rules_python//python/extensions:python.bzl", "python")
-python.toolchain(python_version = "3.8.12", is_default = False)
-python.toolchain(python_version = "3.9", is_default = True)
-```
-""",
+        doc = """Whether to build this target and its transitive deps for a specific python version.""",
     ),
     "package_collisions": attr.string(
         doc = """The action that should be taken when a symlink collision is encountered when creating the venv.

py/private/py_pex_binary.bzl

@@ -2,8 +2,20 @@
 
 Follows [PEP-441 (PEX)](https://peps.python.org/pep-0441/)
 
+## Ensuring a compatible interpreter is used
+
 The resulting zip file does *not* contain a Python interpreter.
 Users are expected to execute the PEX with a compatible interpreter on the runtime system.
+
+Use the `python_interpreter_constraints` to provide an error if a wrong interpreter tries to execute the PEX, for example:
+
+```starlark
+py_pex_binary(
+    python_interpreter_constraints = [
+        "CPython=={major}.{minor}.{patch}",
+    ]
+)
+```
 """
 
 load("@rules_python//python:defs.bzl", "PyInfo")
@@ -138,16 +150,6 @@ _attrs = dict({
 Python interpreter versions this PEX binary is compatible with. A list of semver strings. 
 The placeholder strings `{major}`, `{minor}`, `{patch}` can be used for gathering version 
 information from the hermetic python toolchain.
-
-For example, to enforce same interpreter version that Bazel uses, following can be used.
-
-```starlark
-py_pex_binary
-    python_interpreter_constraints = [
-      "CPython=={major}.{minor}.{patch}"
-    ]
-)
-```
 """,
     ),
     # NB: this is read by _resolve_toolchain in py_semantics.