more feedback incorporated

Author: philsc

python/private/repl.bzl

@@ -1,11 +1,12 @@
 """Implementation of the rules to expose a REPL."""
 
-load("//python:py_binary.bzl", "py_binary")
+load("//python:py_binary.bzl", _py_binary="py_binary")
 
 def _generate_repl_main_impl(ctx):
     stub_repo = ctx.attr.stub.label.repo_name or ctx.workspace_name
     stub_path = "/".join([stub_repo, ctx.file.stub.short_path])
 
+    # Point the generated main file at the stub.
     ctx.actions.expand_template(
         template = ctx.file._template,
         output = ctx.outputs.out,
@@ -33,17 +34,40 @@ _generate_repl_main = rule(
             doc = "The template to use for generating `out`.",
         ),
     },
+    doc = """\
+Generates a "main" script for a py_binary target that starts a Python REPL.
+
+The template is designed to take care of the majority of the logic. The user
+customizes the exact shell that will be started via the stub. The stub is a
+simple shell script that imports the desired shell and then executes it.
+""",
 )
 
 def py_repl_binary(name, stub, deps = [], data = [], **kwargs):
-    """A 
+    """A py_binary target that executes a REPL when run.
+
+    The stub is the script that ultimately decides which shell the REPL will run.
+    It can be as simple as this:
+
+        import code
+        code.interact()
+
+    Or it can load something like IPython instead.
+
+    Args:
+        name: Name of the generated py_binary target.
+        stub: The script that invokes the shell.
+        deps: The dependencies of the py_binary.
+        data: The runtime dependencies of the py_binary.
+        **kwargs: Forwarded to the py_binary.
+    """
     _generate_repl_main(
         name = "%s_py" % name,
         stub = stub,
         out = "%s.py" % name,
     )
 
-    py_binary(
+    _py_binary(
         name = name,
         srcs = [
             ":%s.py" % name,

python/private/repl_template.py

@@ -11,6 +11,9 @@ def start_repl():
     # Simulate Python's behavior when a valid startup script is defined by the
     # PYTHONSTARTUP variable. If this file path fails to load, print the error
     # and revert to the default behavior.
+    #
+    # See upstream for more information:
+    # https://docs.python.org/3/using/cmdline.html#envvar-PYTHONSTARTUP
     if startup_file := os.getenv("PYTHONSTARTUP"):
         try:
             source_code = Path(startup_file).read_text()