docs(gazelle): Add details about python_root directive. (#1782)

While figuring out how to use gazelle with a `src` dir (see
#1775) (I figured it
out by the way, hence this PR), I noticed that the docs were a little
unclear.

This PR updates the `gazelle` docs to include details about the
`python_root` directive and how to use it.

I also fix a the default value for the
`python_generation_mode_per_file_include_init` directive, as it was
incorrectly listed as "package".

Author: dougthor42

gazelle/README.md

@@ -176,8 +176,8 @@ Python-specific directives are as follows:
 |--------------------------------------|-------------------|
 | `# gazelle:python_extension`         |   `enabled`       |
 | Controls whether the Python extension is enabled or not. Sub-packages inherit this value. Can be either "enabled" or "disabled". | |
-| `# gazelle:python_root`              |    n/a            |
-| Sets a Bazel package as a Python root. This is used on monorepos with multiple Python projects that don't share the top-level of the workspace as the root. | |
+| [`# gazelle:python_root`](#directive-python_root) |    n/a            |
+| Sets a Bazel package as a Python root. This is used on monorepos with multiple Python projects that don't share the top-level of the workspace as the root. See [Directive: `python_root`](#directive-python_root) below. | |
 | `# gazelle:python_manifest_file_name`| `gazelle_python.yaml` |
 | Overrides the default manifest file name. | |
 | `# gazelle:python_ignore_files`      |     n/a           |
@@ -188,7 +188,7 @@ Python-specific directives are as follows:
 | Controls whether the Python import statements should be validated. Can be "true" or "false" | |
 | `# gazelle:python_generation_mode`| `package` |
 | Controls the target generation mode. Can be "file", "package", or "project" | |
-| `# gazelle:python_generation_mode_per_file_include_init`| `package` |
+| `# gazelle:python_generation_mode_per_file_include_init`| `false` |
 | Controls whether `__init__.py` files are included as srcs in each generated target when target generation mode is "file". Can be "true", or "false" | |
 | `# gazelle:python_library_naming_convention`| `$package_name$` |
 | Controls the `py_library` naming convention. It interpolates `$package_name$` with the Bazel package name. E.g. if the Bazel package name is `foo`, setting this to `$package_name$_my_lib` would result in a generated target named `foo_my_lib`. | |
@@ -199,6 +199,43 @@ Python-specific directives are as follows:
 | `# gazelle:resolve py ...` | n/a |
 | Instructs the plugin what target to add as a dependency to satisfy a given import statement. The syntax is `# gazelle:resolve py import-string label` where `import-string` is the symbol in the python `import` statement, and `label` is the Bazel label that Gazelle should write in `deps`. | |
 
+
+#### Directive: `python_root`:
+
+Set this directive within the Bazel package that you want to use as the Python root.
+For example, if using a `src` dir (as recommended by the [Python Packaging User
+Guide][python-packaging-user-guide]), then set this directive in `src/BUILD.bazel`:
+
+```starlark
+# ./src/BUILD.bazel
+# Tell gazelle that are python root is the same dir as this Bazel package.
+# gazelle:python_root
+```
+
+Note that the directive does not have any arguments.
+
+Gazelle will then add the necessary `imports` attribute to all targets that it
+generates:
+
+```starlark
+# in ./src/foo/BUILD.bazel
+py_libary(
+    ...
+    imports = [".."],  # Gazelle adds this
+    ...
+)
+
+# in ./src/foo/bar/BUILD.bazel
+py_libary(
+    ...
+    imports = ["../.."],  # Gazelle adds this
+    ...
+)
+```
+
+[python-packaging-user-guide]: https://github.com/pypa/packaging.python.org/blob/4c86169a/source/tutorials/packaging-projects.rst
+
+
 ### Libraries
 
 Python source files are those ending in `.py` but not ending in `_test.py`.