update-repos: insert rules and macros higher in WORKSPACE (bazel-cont…

…rib#876)

update-repos now calls a function, findWorkspaceInsertIndex, which
finds the best place to insert new dependencies. It looks for an index
after repositories containing repository rules are declared and after
loads from files that contain known repository rules. It returns an
index after that index, following any calls that appear to be direct
dependencies.

merger now recognizes a private attribute on unmatched, generated
rules indicating where they should be inserted. I'm not sure if this
is a good interface yet, so marked as unstable.

Updated the Gazelle boilerplate so that the load of
@bazel_gazelle//:deps.bzl appears before go_rules_dependencies. New
dependencies must be added after this loaded (because go_repository
will be loaded from there), but they ought to be added before
go_rules_dependencies, since it's common to override protobuf, x_tools
and other things in there.

Fixes bazel-contrib#865

README.rst

@@ -5,9 +5,6 @@ Gazelle build file generator
 .. _Architecture of Gazelle: Design.rst
 .. _Repository rules: repository.rst
 .. _go_repository: repository.rst#go_repository
-.. _git_repository: repository.rst#git_repository
-.. _http_archive: repository.rst#http_archive
-.. _Gazelle in rules_go: https://github.com/bazelbuild/rules_go/tree/master/go/tools/gazelle
 .. _fix: #fix-and-update
 .. _update: #fix-and-update
 .. _Avoiding conflicts with proto rules: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#avoiding-conflicts
@@ -89,14 +86,13 @@ should look like this:
         ],
     )
 
-    load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
+    load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+    load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
 
     go_rules_dependencies()
 
     go_register_toolchains()
 
-    load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
-
     gazelle_dependencies()
 
 Add the code below to the BUILD or BUILD.bazel file in the root directory
@@ -126,7 +122,7 @@ rule cannot run directly.
 
 .. code::
 
-  $ bazel run //:gazelle -- update-repos -from_file=go.mod
+  $ bazel run //:gazelle -- update-repos -from_file=go.mod -to_macro=deps.bzl%go_dependencies
 
 Running Gazelle with Go
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -399,6 +395,7 @@ The following flags are accepted:
 |                                                                                                       |
 | By default, all languages that this Gazelle was built with are processed.                             |
 +--------------------------------------------------------------+----------------------------------------+
+
 .. _Predefined plugins: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#predefined-plugins
 
 ``update-repos``