add some docs

Author: philsc

docs/toolchains.md

@@ -313,7 +313,7 @@ provide `Python.h`.
 
 This is typically implemented using {obj}`py_cc_toolchain()`, which provides
 {obj}`ToolchainInfo` with the field `py_cc_toolchain` set, which is a
-{obj}`PyCcToolchainInfo` provider instance. 
+{obj}`PyCcToolchainInfo` provider instance.
 
 This toolchain type is intended to hold only _target configuration_ values
 relating to the C/C++ information for the Python runtime. As such, when defining
@@ -467,3 +467,35 @@ Currently the following flags are used to influence toolchain selection:
 * {obj}`--@rules_python//python/config_settings:py_linux_libc` for selecting the Linux libc variant.
 * {obj}`--@rules_python//python/config_settings:py_freethreaded` for selecting
   the freethreaded experimental Python builds available from `3.13.0` onwards.
+
+## Accessing the underlying interpreter
+
+To access the interpreter that bazel manages, you can use the
+`@rules_python//python/bin:interpreter` target. This is a binary target with
+the executable pointing at the `python3` binary plus the relevent runfiles.
+
+```
+$ bazel run @rules_python//python/bin:interpreter
+Python 3.11.1 (main, Jan 16 2023, 22:41:20) [Clang 15.0.7 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+$ bazel run @rules_python//python/bin:interpreter --@rules_python//python/config_settings:python_version=3.12
+Python 3.12.0 (main, Oct  3 2023, 01:27:23) [Clang 17.0.1 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+
+You can also access a specific binary's interpreter this way by using the
+`@rules_python//python/bin:interpreter_src` target.
+
+```
+$ bazel run @rules_python//python/bin:interpreter --@rules_python//python/bin:interpreter_src=//path/to:bin
+Python 3.11.1 (main, Jan 16 2023, 22:41:20) [Clang 15.0.7 ] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+
+:::{note}
+The interpreter target does not provide access to any modules from `py_*`
+targets on its own. Work is ongoing to support that.
+:::

tests/integration/interpreter_test.py

@@ -44,6 +44,7 @@ def test_run_interpreter_3_12(self):
 
     def _run_module_test(self, version):
         """Validates that we can successfully invoke a module from the CLI."""
+        # Pass unformatted JSON to the json.tool module.
         result = self.run_bazel(
             "run",
             f"--@rules_python//python/config_settings:python_version={version}",
@@ -53,6 +54,7 @@ def _run_module_test(self, version):
             "json.tool",
             input = '{"json":"obj"}',
         )
+        # Validate that we get formatted JSON back.
         self.assert_result_matches(result, r'{\n    "json": "obj"\n}')
 
     def test_run_module_3_10(self):