internal/extend_docs.bzl

# 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.

Tests
-----

To write tests for your gazelle extension, you can use [gazelle_generation_test](#gazelle_generation_test),
which will run a gazelle binary of your choosing on a set of test workspaces.


Supported languages
-------------------

Moved to [/README.rst](/README.rst#supported-languages)

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 = [
        "@rules_python//gazelle",  # Use gazelle from rules_python.
        "@bazel_gazelle//language/go",  # Built-in rule from gazelle for Golang.
        "@bazel_gazelle//language/proto",  # Built-in rule from gazelle for Protos.
         # Any languages that depend on Gazelle's proto plugin must come after it.
        "@external_repository//language/gazelle",  # External languages can be added here.
    ],
    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
"""

load(
    "//internal/generationtest:generationtest.bzl",
    _gazelle_generation_test = "gazelle_generation_test",
)
load("gazelle_binary.bzl", _gazelle_binary = "gazelle_binary")

gazelle_binary = _gazelle_binary

gazelle_generation_test = _gazelle_generation_test