chore(docs): move WORKSPACE docs out of primary README (#4209)

Current Bazel nightly versions (pre-releases of Bazel 9) will soon stop
supporting this, so it shouldn't be the first docs we show new users.

Note, I've done the minimal touching of the content, converting
ReStructured Text to Markdown.

Related to
bazel-contrib/bazel-gazelle#1715 (comment)
from a year ago.

Author: alexeagle

README.rst

@@ -9,21 +9,20 @@ Go rules for Bazel_
 .. _Build modes: go/modes.rst
 .. _Bzlmod: https://bazel.build/external/overview#bzlmod
 .. _Go with Bzlmod: docs/go/core/bzlmod.md
+.. _Go with WORKSPACE: docs/go/core/workspace.md
 .. _Core rules: docs/go/core/rules.md
 .. _Coverage: https://bazel.google.cn/docs/coverage
 .. _Dependencies: go/dependencies.rst
 .. _Deprecation schedule: https://github.com/bazelbuild/rules_go/wiki/Deprecation-schedule
 .. _Gopher Slack: https://invite.slack.golangbridge.org/
 .. _gopls integration: https://github.com/bazelbuild/rules_go/wiki/Editor-setup
 .. _Overriding dependencies: go/dependencies.rst#overriding-dependencies
-.. _Proto dependencies: go/dependencies.rst#proto-dependencies
 .. _Proto rules: proto/core.rst
 .. _Protocol buffers: proto/core.rst
 .. _Toolchains: go/toolchains.rst
 .. _Using rules_go on Windows: windows.rst
 .. _bazel-go-discuss: https://groups.google.com/forum/#!forum/bazel-go-discuss
 .. _configuration transition: https://docs.bazel.build/versions/master/skylark/lib/transition.html
-.. _gRPC dependencies: go/dependencies.rst#grpc-dependencies
 .. _gazelle update-repos: https://github.com/bazelbuild/bazel-gazelle#update-repos
 .. _gazelle: https://github.com/bazelbuild/bazel-gazelle
 .. _github.com/bazelbuild/bazel-gazelle: https://github.com/bazelbuild/bazel-gazelle
@@ -202,7 +201,6 @@ Contents
 
 * `Overview`_
 * `Setup`_
-* `protobuf and gRPC`_
 * `FAQ`_
 
 Documentation
@@ -306,302 +304,12 @@ Several additional tools need to be installed and configured.
 Initial project setup
 ~~~~~~~~~~~~~~~~~~~~~
 
-If you are using Bazel's new external dependency management system `Bzlmod`_,
-refer to the dedicated `Go with Bzlmod`_ guide instead.
+There are two ways to setup:
 
-Create a file at the top of your repository named ``WORKSPACE``, and add the
-snippet below (or add to your existing ``WORKSPACE``). This tells Bazel to
-fetch rules_go and its dependencies. Bazel will download a recent supported
-Go toolchain and register it for use.
-
-.. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    http_archive(
-        name = "io_bazel_rules_go",
-        integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-        ],
-    )
-
-    load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-
-    go_rules_dependencies()
-
-    go_register_toolchains(version = "1.23.1")
-
-You can use rules_go at ``master`` by using `git_repository`_ instead of
-`http_archive`_ and pointing to a recent commit.
-
-Add a file named ``BUILD.bazel`` in the root directory of your project.
-You'll need a build file in each directory with Go code, but you'll also need
-one in the root directory, even if your project doesn't have Go code there.
-For a "Hello, world" binary, the file should look like this:
-
-.. code:: bzl
-
-    load("@io_bazel_rules_go//go:def.bzl", "go_binary")
-
-    go_binary(
-        name = "hello",
-        srcs = ["hello.go"],
-    )
-
-You can build this target with ``bazel build //:hello``.
-
-Generating build files
-~~~~~~~~~~~~~~~~~~~~~~
-
-If your project can be built with ``go build``, you can generate and update your
-build files automatically using gazelle_.
-
-Add the ``bazel_gazelle`` repository and its dependencies to your
-``WORKSPACE``. It should look like this:
-
-  .. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    http_archive(
-        name = "io_bazel_rules_go",
-        integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-        ],
-    )
-
-    http_archive(
-        name = "bazel_gazelle",
-        integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-        ],
-    )
-
-    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(version = "1.23.1")
-
-    gazelle_dependencies()
-
-Add the code below to the ``BUILD.bazel`` file in your project's root directory.
-Replace the string after ``prefix`` with an import path prefix that matches your
-project. It should be the same as your module path, if you have a ``go.mod``
-file.
-
-.. code:: bzl
-
-    load("@bazel_gazelle//:def.bzl", "gazelle")
-
-    # gazelle:prefix github.com/example/project
-    gazelle(name = "gazelle")
-
-This declares a ``gazelle`` binary rule, which you can run using the command
-below:
-
-.. code:: bash
-
-    bazel run //:gazelle
-
-This will generate a ``BUILD.bazel`` file with `go_library`_, `go_binary`_, and
-`go_test`_ targets for each package in your project. You can run the same
-command in the future to update existing build files with new source files,
-dependencies, and options.
-
-Writing build files by hand
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If your project doesn't follow ``go build`` conventions or you prefer not to use
-gazelle_, you can write build files by hand.
-
-In each directory that contains Go code, create a file named ``BUILD.bazel``
-Add a ``load`` statement at the top of the file for the rules you use.
-
-.. code:: bzl
-
-    load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library", "go_test")
-
-For each library, add a `go_library`_ rule like the one below.  Source files are
-listed in the ``srcs`` attribute. Imported packages outside the standard library
-are listed in the ``deps`` attribute using `Bazel labels`_ that refer to
-corresponding `go_library`_ rules. The library's import path must be specified
-with the ``importpath`` attribute.
-
-.. code:: bzl
-
-    go_library(
-        name = "foo_library",
-        srcs = [
-            "a.go",
-            "b.go",
-        ],
-        importpath = "github.com/example/project/foo",
-        deps = [
-            "//tools",
-            "@org_golang_x_utils//stuff",
-        ],
-        visibility = ["//visibility:public"],
-    )
-
-For tests, add a `go_test`_ rule like the one below. The library being tested
-should be listed in an ``embed`` attribute.
-
-.. code:: bzl
-
-    go_test(
-        name = "foo_test",
-        srcs = [
-            "a_test.go",
-            "b_test.go",
-        ],
-        embed = [":foo_lib"],
-        deps = [
-            "//testtools",
-            "@org_golang_x_utils//morestuff",
-        ],
-    )
-
-For binaries, add a `go_binary`_ rule like the one below.
-
-.. code:: bzl
-
-    go_binary(
-        name = "foo",
-        srcs = ["main.go"],
-    )
-
-Adding external repositories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For each Go repository, add a `go_repository`_ rule to ``WORKSPACE`` like the
-one below.  This rule comes from the Gazelle repository, so you will need to
-load it. `gazelle update-repos`_ can generate or update these rules
-automatically from a go.mod or Gopkg.lock file.
-
-.. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    # Download the Go rules.
-    http_archive(
-        name = "io_bazel_rules_go",
-        integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-        ],
-    )
-
-    # Download Gazelle.
-    http_archive(
-        name = "bazel_gazelle",
-        integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-        ],
-    )
-
-    # Load macros and repository rules.
-    load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-    load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
-
-    # Declare Go direct dependencies.
-    go_repository(
-        name = "org_golang_x_net",
-        importpath = "golang.org/x/net",
-        sum = "h1:7EYJ93RZ9vYSZAIb2x3lnuvqO5zneoD6IvWjuhfxjTs=",
-        version = "v0.23.0",
-    )
-
-    # Declare indirect dependencies and register toolchains.
-    go_rules_dependencies()
-
-    go_register_toolchains(version = "1.23.1")
-
-    gazelle_dependencies()
-
-
-protobuf and gRPC
------------------
-
-To generate code from protocol buffers, you'll need to add a dependency on
-``com_google_protobuf`` to your ``WORKSPACE``.
-
-.. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    http_archive(
-        name = "com_google_protobuf",
-        sha256 = "535fbf566d372ccf3a097c374b26896fa044bf4232aef9cab37bd1cc1ba4e850",
-        strip_prefix = "protobuf-3.15.0",
-        urls = [
-            "https://mirror.bazel.build/github.com/protocolbuffers/protobuf/archive/v3.15.0.tar.gz",
-            "https://github.com/protocolbuffers/protobuf/archive/v3.15.0.tar.gz",
-        ],
-    )
-
-    load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
-
-    protobuf_deps()
-
-You'll need a C/C++ toolchain registered for the execution platform (the
-platform where Bazel runs actions) to build protoc.
-
-The `proto_library`_ rule is provided by the ``rules_proto`` repository.
-``protoc-gen-go``, the Go proto compiler plugin, is provided by the
-``com_github_golang_protobuf`` repository. Both are declared by
-`go_rules_dependencies`_. You won't need to declare an explicit dependency
-unless you specifically want to use a different version. See `Overriding
-dependencies`_ for instructions on using a different version.
-
-gRPC dependencies are not declared by default (there are too many). You can
-declare them in WORKSPACE using `go_repository`_. You may want to use
-`gazelle update-repos`_ to import them from ``go.mod``.
-
-See `Proto dependencies`_, `gRPC dependencies`_ for more information. See also
-`Avoiding conflicts`_.
-
-Once all dependencies have been registered, you can declare `proto_library`_
-and `go_proto_library`_ rules to generate and compile Go code from .proto
-files.
-
-.. code:: bzl
-
-    load("@rules_proto//proto:defs.bzl", "proto_library")
-    load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
-
-    proto_library(
-        name = "foo_proto",
-        srcs = ["foo.proto"],
-        deps = ["//bar:bar_proto"],
-        visibility = ["//visibility:public"],
-    )
-
-    go_proto_library(
-        name = "foo_go_proto",
-        importpath = "github.com/example/protos/foo_proto",
-        protos = [":foo_proto"],
-        visibility = ["//visibility:public"],
-    )
-
-A ``go_proto_library`` target may be imported and depended on like a normal
-``go_library``.
-
-Note that recent versions of rules_go support both APIv1
-(``github.com/golang/protobuf``) and APIv2 (``google.golang.org/protobuf``).
-By default, code is generated with
-``github.com/golang/protobuf/cmd/protoc-gen-gen`` for compatibility with both
-interfaces. Client code may import use either runtime library or both.
+* With Bazel's external dependency management system `Bzlmod`_,
+refer to the dedicated `Go with Bzlmod`_ guide.
+* With the older ``WORKSPACE`` dependency file, refer to the
+`Go with WORKSPACE`_ setup docs.
 
 FAQ
 ---