diff --git a/BUILD.bazel b/BUILD.bazel index 37175004b..856705cfc 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -32,7 +32,7 @@ nogo( visibility = ["//visibility:public"], ) -exports_files(["WORKSPACE", "repository.md"]) +exports_files(["WORKSPACE", "extend.md", "repository.md"]) filegroup( name = "all_files", diff --git a/README.rst b/README.rst index d01a402c0..220eea3e6 100644 --- a/README.rst +++ b/README.rst @@ -3,17 +3,17 @@ Gazelle build file generator .. All external links are here .. _Architecture of Gazelle: Design.rst -.. _Repository rules: repository.rst -.. _go_repository: repository.rst#go_repository +.. _Repository rules: repository.md +.. _go_repository: repository.md#go_repository .. _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 .. _gazelle rule: #bazel-rule .. _doublestar.Match: https://github.com/bmatcuk/doublestar#match -.. _Extending Gazelle: extend.rst -.. _Supported languages: extend.rst#supported-languages +.. _Extending Gazelle: extend.md +.. _Supported languages: extend.md#supported-languages .. _extended: `Extending Gazelle`_ -.. _gazelle_binary: extend.rst#gazelle_binary +.. _gazelle_binary: extend.md#gazelle_binary .. _import_prefix: https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.import_prefix .. _strip_import_prefix: https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.strip_import_prefix .. _buildozer: https://github.com/bazelbuild/buildtools/tree/master/buildozer diff --git a/WORKSPACE b/WORKSPACE index 5fcc89e68..6270c7e5b 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -15,10 +15,13 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "io_bazel_rules_go", - sha256 = "2b1641428dff9018f9e85c0384f03ec6c10660d935b750e3fa1492a281a53b0f", + sha256 = "e0c127187c63f96158a7fd609300e216f70b44912806f62f0d17c7d3a3872bc1", + strip_prefix = "rules_go-027d78bed3952d73c6fb7099b3247f903aa7318d", urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip", - "https://github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip", + # Need a prerelease version of rules_go to pick up bzl_library fixes + # https://github.com/bazelbuild/rules_go/pull/2942 + # Can go back to release artifact after 0.30 release + "https://github.com/bazelbuild/rules_go/archive/027d78bed3952d73c6fb7099b3247f903aa7318d.zip", ], ) diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 3fb1594dd..e276ffdbf 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -10,6 +10,7 @@ load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") _DOC_SRCS = { "//internal:repository_docs": "repository.md", + "//internal:extend_docs": "extend.md", } [ diff --git a/extend.md b/extend.md new file mode 100644 index 000000000..129186b97 --- /dev/null +++ b/extend.md @@ -0,0 +1,155 @@ + + + +Extending Gazelle +================= + +Gazelle started out as a build file generator for Go projects, but it can be +extended to support other languages and custom sets of rules. + +To extend Gazelle, you must do three things: + +* Write a [go_library] with a function named `NewLanguage` that provides an + implementation of the [Language] interface. This interface provides hooks for + generating rules, parsing configuration directives, and resolving imports + to Bazel labels. By convention, the library's package name should match + the language (for example, `proto` or `bzl`). +* Write a [gazelle_binary](#gazelle_binary) rule. Include your library in the `languages` + list. +* Write a [gazelle] rule that points to your `gazelle_binary`. When you run + `bazel run //:gazelle`, your binary will be built and executed instead of + the default binary. + +Supported languages +------------------- + +Some extensions have been published by the community. + +* [bazel-skylib] has an extension for generating `bzl_library` rules. + See [@bazel_skylib//gazelle/bzl]. +* [rules_python] has an extension for generating `py_library`, `py_binary`, and + `py_test` rules (currently pending in PR [#514]). +* [rules_sass] has an extension for generating `sass_library` and + `sass_binary` rules (currently pending in PR [#75]). +* [rules_r] has an extension for generating rules for R package builds and + tests. +* Ecosia's [bazel_rules_nodejs_contrib] has an extension for generating + `js_library`, `jest_node_test`, `js_import`, and `ts_library` rules. +* Tweag's [rules_haskell] has an extension, [gazelle_cabal], for generating rules from Cabal files + +If you have an extension you'd like linked here, please open a PR! + +Example +------- + +**TODO:** Add a self-contained, concise, realistic example. + +Gazelle itself is built using the model described above, so it may serve as +an example. + +[//language/proto:go_default_library] and [//language/go:go_default_library] +both implement the [Language] +interface. There is also [//internal/gazellebinarytest:go_default_library], +a stub implementation used for testing. + +`//cmd/gazelle` is a `gazelle_binary` rule that includes both of these +libraries through the `DEFAULT_LANGUAGES` list (you may want to use +`DEFAULT_LANGUAGES` in your own rule). + +```starlark +load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary") + +gazelle_binary( + name = "gazelle", + languages = DEFAULT_LANGUAGES, + visibility = ["//visibility:public"], +) +``` + +This binary can be invoked using a `gazelle` rule like this: + +```starlark +load("@bazel_gazelle//:def.bzl", "gazelle") + +# gazelle:prefix example.com/project +gazelle( + name = "gazelle", + gazelle = "//:my_gazelle_binary", +) +``` + +You can run this with `bazel run //:gazelle`. + +Interacting with protos +----------------------- + +The proto extension ([//language/proto:go_default_library]) gathers metadata +from .proto files and generates `proto_library` rules based on that metadata. +Extensions that generate language-specific proto rules (e.g., +`go_proto_library`) may use this metadata. + +For API reference, see the [proto godoc]. + +To get proto configuration information, call [proto.GetProtoConfig]. This is +mainly useful for discovering the current proto mode. + +To get information about `proto_library` rules, examine the `OtherGen` +list of rules passed to `language.GenerateRules`. This is a list of rules +generated by other language extensions, and it will include `proto_library` +rules in each directory, if there were any. For each of these rules, you can +call `r.PrivateAttr(proto.PackageKey)` to get a [proto.Package] record. This +includes the proto package name, as well as source names, imports, and options. + +[Language]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language#Language +[//internal/gazellebinarytest:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/internal/gazellebinarytest +[//language/go:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/go +[//language/proto:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/proto +[gazelle]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule +[go_binary]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-binary +[go_library]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-library +[proto godoc]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto +[proto.GetProtoConfig]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#GetProtoConfig +[proto.Package]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#Package +[rules_python]: https://github.com/bazelbuild/rules_python +[rules_r]: https://github.com/grailbio/rules_r +[rules_sass]: https://github.com/bazelbuild/rules_sass +[rules_haskell]: https://github.com/tweag/rules_haskell +[bazel_rules_nodejs_contrib]: https://github.com/ecosia/bazel_rules_nodejs_contrib#build-file-generation +[bazel-skylib]: https://github.com/bazelbuild/bazel-skylib +[@bazel_skylib//gazelle/bzl]: https://github.com/bazelbuild/bazel-skylib/tree/master/gazelle/bzl +[gazelle_cabal]: https://github.com/tweag/gazelle_cabal +[#75]: https://github.com/bazelbuild/rules_sass/pull/75 +[#514]: https://github.com/bazelbuild/rules_python/pull/514 +[#803]: https://github.com/bazelbuild/bazel-gazelle/issues/803 + + + + +## gazelle_binary + +
+gazelle_binary(name, languages) ++ +The `gazelle_binary` rule builds a Go binary that incorporates a list of +language extensions. This requires generating a small amount of code that +must be compiled into Gazelle's main package, so the normal [go_binary] +rule is not used. + +When the binary runs, each language extension is run sequentially. This affects +the order that rules appear in generated build files. Metadata may be produced +by an earlier extension and consumed by a later extension. For example, the +proto extension stores metadata in hidden attributes of generated +`proto_library` rules. The Go extension uses this metadata to generate +`go_proto_library` rules. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| languages | A list of language extensions the Gazelle binary will use.
NewLanguage
with no parameters that returns a value assignable to [Language]. | List of labels | required | |
+
+
diff --git a/extend.rst b/extend.rst
index 3f23e5018..a1ede1754 100644
--- a/extend.rst
+++ b/extend.rst
@@ -1,191 +1,4 @@
Extending Gazelle
=================
-.. Begin directives
-.. _Language: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language#Language
-.. _`//internal/gazellebinarytest:go_default_library`: https://github.com/bazelbuild/bazel-gazelle/tree/master/internal/gazellebinarytest
-.. _`//language/go:go_default_library`: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/go
-.. _`//language/proto:go_default_library`: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/proto
-.. _gazelle: https://github.com/bazelbuild/bazel-gazelle#bazel-rule
-.. _go_binary: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-binary
-.. _go_library: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-library
-.. _proto godoc: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto
-.. _proto.GetProtoConfig: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#GetProtoConfig
-.. _proto.Package: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#Package
-.. _rules_r: https://github.com/grailbio/rules_r
-.. _rules_sass: https://github.com/bazelbuild/rules_sass
-.. _rules_haskell: https://github.com/tweag/rules_haskell
-.. _bazel_rules_nodejs_contrib: https://github.com/ecosia/bazel_rules_nodejs_contrib#build-file-generation
-.. _bazel-skylib: https://github.com/bazelbuild/bazel-skylib
-.. _@bazel_skylib//gazelle/bzl: https://github.com/bazelbuild/bazel-skylib/tree/master/gazelle/bzl
-.. _gazelle_cabal: https://github.com/tweag/gazelle_cabal
-.. _#75: https://github.com/bazelbuild/rules_sass/pull/75
-.. _#803: https://github.com/bazelbuild/bazel-gazelle/issues/803
-
-.. role:: cmd(code)
-.. role:: flag(code)
-.. role:: direc(code)
-.. role:: param(kbd)
-.. role:: type(emphasis)
-.. role:: value(code)
-.. |mandatory| replace:: **mandatory value**
-.. End directives
-
-Gazelle started out as a build file generator for Go projects, but it can be
-extended to support other languages and custom sets of rules.
-
-To extend Gazelle, you must do three things:
-
-* Write a `go_library`_ with a function named ``NewLanguage`` that provides an
- implementation of the Language_ interface. This interface provides hooks for
- generating rules, parsing configuration directives, and resolving imports
- to Bazel labels. By convention, the library's package name should match
- the language (for example, ``proto`` or ``bzl``).
-* Write a `gazelle_binary`_ rule. Include your library in the ``languages``
- list.
-* Write a `gazelle`_ rule that points to your ``gazelle_binary``. When you run
- ``bazel run //:gazelle``, your binary will be built and executed instead of
- the default binary.
-
-Supported languages
--------------------
-
-Some extensions have been published by the community.
-
-* `bazel-skylib`_ has an extension for generating ``bzl_library`` rules.
- See `@bazel_skylib//gazelle/bzl`_.
-* `rules_sass`_ has an extension for generating ``sass_library`` and
- ``sass_binary`` rules (currently pending in PR `#75`_).
-* `rules_r`_ has an extension for generating rules for R package builds and
- tests.
-* Ecosia's `bazel_rules_nodejs_contrib`_ has an extension for generating
- ``js_library``, ``jest_node_test``, ``js_import``, and ``ts_library`` rules.
-* Tweag's `rules_haskell`_ has an extension, `gazelle_cabal`_, for generating rules from Cabal files
-
-If you have an extension you'd like linked here, please open a PR!
-
-Example
--------
-
-**TODO:** Add a self-contained, concise, realistic example.
-
-Gazelle itself is built using the model described above, so it may serve as
-an example.
-
-`//language/proto:go_default_library`_ and `//language/go:go_default_library`_
-both implement the `Language`_
-interface. There is also `//internal/gazellebinarytest:go_default_library`_,
-a stub implementation used for testing.
-
-``//cmd/gazelle`` is a ``gazelle_binary`` rule that includes both of these
-libraries through the ``DEFAULT_LANGUAGES`` list (you may want to use
-``DEFAULT_LANGUAGES`` in your own rule).
-
-.. code:: bzl
-
- load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary")
-
- gazelle_binary(
- name = "gazelle",
- languages = DEFAULT_LANGUAGES,
- visibility = ["//visibility:public"],
- )
-
-This binary can be invoked using a ``gazelle`` rule like this:
-
-.. code:: bzl
-
- load("@bazel_gazelle//:def.bzl", "gazelle")
-
- # gazelle:prefix example.com/project
- gazelle(
- name = "gazelle",
- gazelle = "//:my_gazelle_binary",
- )
-
-You can run this with ``bazel run //:gazelle``.
-
-gazelle_binary
---------------
-
-The ``gazelle_binary`` rule builds a Go binary that incorporates a list of
-language extensions. This requires generating a small amount of code that
-must be compiled into Gazelle's main package, so the normal `go_binary`_
-rule is not used.
-
-When the binary runs, each language extension is run sequentially. This affects
-the order that rules appear in generated build files. Metadata may be produced
-by an earlier extension and consumed by a later extension. For example, the
-proto extension stores metadata in hidden attributes of generated
-``proto_library`` rules. The Go extension uses this metadata to generate
-``go_proto_library`` rules.
-
-The following attributes are supported on the ``gazelle_binary`` rule.
-
-+----------------------+---------------------+--------------------------------------+
-| **Name** | **Type** | **Default value** |
-+======================+=====================+======================================+
-| :param:`languages` | :type:`label_list` | |mandatory| |
-+----------------------+---------------------+--------------------------------------+
-| A list of language extensions the Gazelle binary will use. |
-| |
-| Each extension must be a `go_library`_ or something compatible. Each extension |
-| must export a function named ``NewLanguage`` with no parameters that returns |
-| a value assignable to `Language`_. |
-+----------------------+---------------------+--------------------------------------+
-
-The following attributes are deprecated (`#803`_):
-
-+----------------------+---------------------+--------------------------------------+
-| **Name** | **Type** | **Default value** |
-+======================+=====================+======================================+
-| :param:`pure` | :type:`string` | :value:`auto` |
-+----------------------+---------------------+--------------------------------------+
-| Same meaning as `go_binary`_. It may be necessary to set this to avoid |
-| command flags that affect both host and target configurations. |
-+----------------------+---------------------+--------------------------------------+
-| :param:`static` | :type:`string` | :value:`auto` |
-+----------------------+---------------------+--------------------------------------+
-| Same meaning as `go_binary`_. It may be necessary to set this to avoid |
-| command flags that affect both host and target configurations. |
-+----------------------+---------------------+--------------------------------------+
-| :param:`race` | :type:`string` | :value:`auto` |
-+----------------------+---------------------+--------------------------------------+
-| Same meaning as `go_binary`_. It may be necessary to set this to avoid |
-| command flags that affect both host and target configurations. |
-+----------------------+---------------------+--------------------------------------+
-| :param:`msan` | :type:`string` | :value:`auto` |
-+----------------------+---------------------+--------------------------------------+
-| Same meaning as `go_binary`_. It may be necessary to set this to avoid |
-| command flags that affect both host and target configurations. |
-+----------------------+---------------------+--------------------------------------+
-| :param:`goos` | :type:`string` | :value:`auto` |
-+----------------------+---------------------+--------------------------------------+
-| Same meaning as `go_binary`_. It may be necessary to set this to avoid |
-| command flags that affect both host and target configurations. |
-+----------------------+---------------------+--------------------------------------+
-| :param:`goarch` | :type:`string` | :value:`auto` |
-+----------------------+---------------------+--------------------------------------+
-| Same meaning as `go_binary`_. It may be necessary to set this to avoid |
-| command flags that affect both host and target configurations. |
-+----------------------+---------------------+--------------------------------------+
-
-Interacting with protos
------------------------
-
-The proto extension (`//language/proto:go_default_library`_) gathers metadata
-from .proto files and generates ``proto_library`` rules based on that metadata.
-Extensions that generate language-specific proto rules (e.g.,
-``go_proto_library``) may use this metadata.
-
-For API reference, see the `proto godoc`_.
-
-To get proto configuration information, call `proto.GetProtoConfig`_. This is
-mainly useful for discovering the current proto mode.
-
-To get information about ``proto_library`` rules, examine the ``OtherGen``
-list of rules passed to ``language.GenerateRules``. This is a list of rules
-generated by other language extensions, and it will include ``proto_library``
-rules in each directory, if there were any. For each of these rules, you can
-call ``r.PrivateAttr(proto.PackageKey)`` to get a `proto.Package`_ record. This
-includes the proto package name, as well as source names, imports, and options.
+`Moved to markdown <./extend.md>`_
diff --git a/internal/BUILD.bazel b/internal/BUILD.bazel
index 6fa6c557e..d61873eb8 100644
--- a/internal/BUILD.bazel
+++ b/internal/BUILD.bazel
@@ -20,6 +20,7 @@ go_bazel_test(
exports_files(
[
"gazelle.bash.in",
+ "extend_docs.bzl",
"repository_docs.bzl",
"list_repository_tools_srcs.go",
"repository_rules_test_errors.patch",
@@ -123,4 +124,11 @@ bzl_library(
":overlay_repository",
],
visibility = ["//:__subpackages__"],
+)
+
+bzl_library(
+ name = "extend_docs",
+ srcs = ["extend_docs.bzl"],
+ deps = [":gazelle_binary"],
+ visibility = ["//:__subpackages__"],
)
\ No newline at end of file
diff --git a/internal/extend_docs.bzl b/internal/extend_docs.bzl
new file mode 100644
index 000000000..d7cba1b9f
--- /dev/null
+++ b/internal/extend_docs.bzl
@@ -0,0 +1,128 @@
+# Module used by stardoc to generate API documentation.
+# Not meant for use by bazel-gazelle users.
+"""
+Extending Gazelle
+=================
+
+Gazelle started out as a build file generator for Go projects, but it can be
+extended to support other languages and custom sets of rules.
+
+To extend Gazelle, you must do three things:
+
+* Write a [go_library] with a function named `NewLanguage` that provides an
+ implementation of the [Language] interface. This interface provides hooks for
+ generating rules, parsing configuration directives, and resolving imports
+ to Bazel labels. By convention, the library's package name should match
+ the language (for example, `proto` or `bzl`).
+* Write a [gazelle_binary](#gazelle_binary) rule. Include your library in the `languages`
+ list.
+* Write a [gazelle] rule that points to your `gazelle_binary`. When you run
+ `bazel run //:gazelle`, your binary will be built and executed instead of
+ the default binary.
+
+Supported languages
+-------------------
+
+Some extensions have been published by the community.
+
+* [bazel-skylib] has an extension for generating `bzl_library` rules.
+ See [@bazel_skylib//gazelle/bzl].
+* [rules_python] has an extension for generating `py_library`, `py_binary`, and
+ `py_test` rules (currently pending in PR [#514]).
+* [rules_sass] has an extension for generating `sass_library` and
+ `sass_binary` rules (currently pending in PR [#75]).
+* [rules_r] has an extension for generating rules for R package builds and
+ tests.
+* Ecosia's [bazel_rules_nodejs_contrib] has an extension for generating
+ `js_library`, `jest_node_test`, `js_import`, and `ts_library` rules.
+* Tweag's [rules_haskell] has an extension, [gazelle_cabal], for generating rules from Cabal files
+
+If you have an extension you'd like linked here, please open a PR!
+
+Example
+-------
+
+**TODO:** Add a self-contained, concise, realistic example.
+
+Gazelle itself is built using the model described above, so it may serve as
+an example.
+
+[//language/proto:go_default_library] and [//language/go:go_default_library]
+both implement the [Language]
+interface. There is also [//internal/gazellebinarytest:go_default_library],
+a stub implementation used for testing.
+
+`//cmd/gazelle` is a `gazelle_binary` rule that includes both of these
+libraries through the `DEFAULT_LANGUAGES` list (you may want to use
+`DEFAULT_LANGUAGES` in your own rule).
+
+```starlark
+load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle_binary")
+
+gazelle_binary(
+ name = "gazelle",
+ languages = DEFAULT_LANGUAGES,
+ visibility = ["//visibility:public"],
+)
+```
+
+This binary can be invoked using a `gazelle` rule like this:
+
+```starlark
+load("@bazel_gazelle//:def.bzl", "gazelle")
+
+# gazelle:prefix example.com/project
+gazelle(
+ name = "gazelle",
+ gazelle = "//:my_gazelle_binary",
+)
+```
+
+You can run this with `bazel run //:gazelle`.
+
+Interacting with protos
+-----------------------
+
+The proto extension ([//language/proto:go_default_library]) gathers metadata
+from .proto files and generates `proto_library` rules based on that metadata.
+Extensions that generate language-specific proto rules (e.g.,
+`go_proto_library`) may use this metadata.
+
+For API reference, see the [proto godoc].
+
+To get proto configuration information, call [proto.GetProtoConfig]. This is
+mainly useful for discovering the current proto mode.
+
+To get information about `proto_library` rules, examine the `OtherGen`
+list of rules passed to `language.GenerateRules`. This is a list of rules
+generated by other language extensions, and it will include `proto_library`
+rules in each directory, if there were any. For each of these rules, you can
+call `r.PrivateAttr(proto.PackageKey)` to get a [proto.Package] record. This
+includes the proto package name, as well as source names, imports, and options.
+
+[Language]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language#Language
+[//internal/gazellebinarytest:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/internal/gazellebinarytest
+[//language/go:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/go
+[//language/proto:go_default_library]: https://github.com/bazelbuild/bazel-gazelle/tree/master/language/proto
+[gazelle]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule
+[go_binary]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-binary
+[go_library]: https://github.com/bazelbuild/rules_go/blob/master/go/core.rst#go-library
+[proto godoc]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto
+[proto.GetProtoConfig]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#GetProtoConfig
+[proto.Package]: https://godoc.org/github.com/bazelbuild/bazel-gazelle/language/proto#Package
+[rules_python]: https://github.com/bazelbuild/rules_python
+[rules_r]: https://github.com/grailbio/rules_r
+[rules_sass]: https://github.com/bazelbuild/rules_sass
+[rules_haskell]: https://github.com/tweag/rules_haskell
+[bazel_rules_nodejs_contrib]: https://github.com/ecosia/bazel_rules_nodejs_contrib#build-file-generation
+[bazel-skylib]: https://github.com/bazelbuild/bazel-skylib
+[@bazel_skylib//gazelle/bzl]: https://github.com/bazelbuild/bazel-skylib/tree/master/gazelle/bzl
+[gazelle_cabal]: https://github.com/tweag/gazelle_cabal
+[#75]: https://github.com/bazelbuild/rules_sass/pull/75
+[#514]: https://github.com/bazelbuild/rules_python/pull/514
+[#803]: https://github.com/bazelbuild/bazel-gazelle/issues/803
+"""
+
+load("gazelle_binary.bzl", _gazelle_binary = "gazelle_binary")
+
+gazelle_binary = _gazelle_binary
diff --git a/internal/gazelle_binary.bzl b/internal/gazelle_binary.bzl
index 0e1afb342..2517675fc 100644
--- a/internal/gazelle_binary.bzl
+++ b/internal/gazelle_binary.bzl
@@ -76,9 +76,25 @@ var languages = []language.Language{{
_gazelle_binary_kwargs = {
"implementation": _gazelle_binary_impl,
+ "doc": """The `gazelle_binary` rule builds a Go binary that incorporates a list of
+language extensions. This requires generating a small amount of code that
+must be compiled into Gazelle's main package, so the normal [go_binary]
+rule is not used.
+
+When the binary runs, each language extension is run sequentially. This affects
+the order that rules appear in generated build files. Metadata may be produced
+by an earlier extension and consumed by a later extension. For example, the
+proto extension stores metadata in hidden attributes of generated
+`proto_library` rules. The Go extension uses this metadata to generate
+`go_proto_library` rules.
+""",
"attrs": {
"languages": attr.label_list(
- doc = "A list of language extensions the Gazelle binary will use",
+ doc = """A list of language extensions the Gazelle binary will use.
+
+ Each extension must be a [go_library] or something compatible. Each extension
+ must export a function named `NewLanguage` with no parameters that returns
+ a value assignable to [Language].""",
providers = [GoArchive],
mandatory = True,
allow_empty = False,
diff --git a/internal/go_repository.bzl b/internal/go_repository.bzl
index 27b8b0b84..406b5cff8 100644
--- a/internal/go_repository.bzl
+++ b/internal/go_repository.bzl
@@ -478,7 +478,7 @@ go_repository = repository_rule(
),
},
)
-"""See repository.rst#go-repository for full documentation."""
+"""See repository.md#go-repository for full documentation."""
# Copied from @bazel_tools//tools/build_defs/repo:utils.bzl
def patch(ctx):