Update documentation for py_binary generation

adzenith · adzenith · commit bc9092460230 · 2024-01-08T12:16:14.000-08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -40,6 +40,10 @@ A brief description of the categories of changes:
 * (toolchains) `py_runtime` can now take an executable target. Note: runfiles
   from the target are not supported yet.
 
+* (gazelle) When `python_generation_mode` is set to `file`, create one `py_binary`
+  target for each file with `if __name__ == "__main__"` instead of just one
+  `py_binary` for the whole module.
+
 ### Fixed
 
 * (gazelle) The gazelle plugin helper was not working with Python toolchains 3.11
diff --git a/gazelle/README.md b/gazelle/README.md
@@ -250,8 +250,20 @@ When no such entry point exists, Gazelle will look for a line like this in the t
 if __name == "__main__":
 ```
 
-Gazelle will create `py_binary` target will be created for every module with such line, with the target name
-being the same as module name.
+Gazelle will create a `py_binary` target for every module with such a line, with
+the target name the same as module name.
+
+If `python_generation_mode` is set to `file`, then instead one `py_binary` target
+is created for each file with such a line, and the name of the target is set to
+match the name of the script.
+
+Note that it's possible for another script to depend on a `py_binary` target and
+import from the `py_binary`'s scripts. This can have possible negative effects on
+Bazel analysis time and runfiles size compared to depending on a `py_library`
+target. The simplest way to avoid these negative effects is to extract library
+code into a separate script without a `main` line. Gazelle will then create a
+`py_library` target for that library code, and then other scripts can depend on
+that library.
 
 ## Developer Notes
 
