fix(gazelle): Do not build proto targets with default Gazelle (#3216)

Fixes #3209.

Revert the change to `//:gazelle_binary` so that it once again only
generates python code. We then create a new, private target
`//:_gazelle_binary_with_proto` that gets used by tests.

Update docs accordingly.

Longer term, I'd like to adjust the `test.yaml` file to include a
section:

```yaml
config:
  gazelle_binary: _gazelle_binary_with_proto
```

So that test cases that need to generate `(py_)proto_library` targets
can use the multi-lang Gazelle binary and that tests that do _not_ need
to generate proto targets can use the single-lang Gazelle binary.

However, there were some minor roadblocks in doing so and thus I'm doing
this quick-to-implement method instead.

(cherry picked from commit 2ed714f9bd3c7df8c1de351455fb8d8d340f76e4)

CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc3d7bb..9a89d24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -159,6 +159,8 @@
   dep is not added to the {obj}`py_test` target.
 * (gazelle) New directive `gazelle:python_generate_proto`; when `true`,
   Gazelle generates `py_proto_library` rules for `proto_library`. `false` by default.
+    * Note: Users must manually configure their Gazelle target to support the
+      proto language.
 * (gazelle) New directive `gazelle:python_proto_naming_convention`; controls
   naming of `py_proto_library` rules.
 

gazelle/docs/directives.md

diff --git a/gazelle/docs/directives.md b/gazelle/docs/directives.md
index ecc30a9..a553226 100644
--- a/gazelle/docs/directives.md
+++ b/gazelle/docs/directives.md
@@ -636,6 +636,30 @@
 `MODULE.bazel`, and otherwise falling back to `@com_google_protobuf` for
 compatibility with `WORKSPACE`.
 
+:::{note}
+In order to use this, you must manually configure Gazelle to target multiple
+languages. Place this in your root `BUILD.bazel` file:
+
+```
+load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
+
+gazelle_binary(
+    name = "gazelle_multilang",
+    languages = [
+        "@bazel_gazelle//language/proto",
+        # The python gazelle plugin must be listed _after_ the proto language.
+        "@rules_python_gazelle_plugin//python",
+    ],
+)
+
+gazelle(
+    name = "gazelle",
+    gazelle = "//:gazelle_multilang",
+)
+```
+:::
+
+
 For example, in a package with `# gazelle:python_generate_proto true` and a
 `foo.proto`, if you have both the proto extension and the Python extension
 loaded into Gazelle, you'll get something like:

gazelle/python/BUILD.bazel

diff --git a/gazelle/python/BUILD.bazel b/gazelle/python/BUILD.bazel
index b6ca8ad..b988e49 100644
--- a/gazelle/python/BUILD.bazel
+++ b/gazelle/python/BUILD.bazel
@@ -70,6 +70,7 @@
     name = "python_test",
     srcs = ["python_test.go"],
     data = [
+        ":_gazelle_binary_with_proto",
         ":gazelle_binary",
     ],
     test_dirs = glob(
@@ -90,11 +91,18 @@
 
 gazelle_binary(
     name = "gazelle_binary",
+    languages = [":python"],
+    visibility = ["//visibility:public"],
+)
+
+# Only used by testing
+gazelle_binary(
+    name = "_gazelle_binary_with_proto",
     languages = [
         "@bazel_gazelle//language/proto",
         ":python",
     ],
-    visibility = ["//visibility:public"],
+    visibility = ["//visibility:private"],
 )
 
 filegroup(

gazelle/python/python_test.go

diff --git a/gazelle/python/python_test.go b/gazelle/python/python_test.go
index dd8c241..e7b95cc 100644
--- a/gazelle/python/python_test.go
+++ b/gazelle/python/python_test.go
@@ -38,7 +38,7 @@
 const (
 	extensionDir      = "python" + string(os.PathSeparator)
 	testDataPath      = extensionDir + "testdata" + string(os.PathSeparator)
-	gazelleBinaryName = "gazelle_binary"
+	gazelleBinaryName = "_gazelle_binary_with_proto"
 )
 
 func TestGazelleBinary(t *testing.T) {