Stardoc generates extras.md

.bazelci/presubmit.yml

@@ -327,3 +327,7 @@ tasks:
     - "-//tests/legacy/test_chdir:go_default_test"
     - "-//tests/legacy/test_rundir:go_default_test"
     - "-//tests/legacy/transitive_data:go_default_test"
+    # Stardoc produces different line-endings on windows,
+    # so the documentation it generates doesn't match the checked in files.
+    # - Tracking issue https://github.com/bazelbuild/stardoc/issues/42.
+    - "-//docs:all"

README.rst

@@ -37,7 +37,7 @@ Go rules for Bazel_
 .. _go_binary: go/core.rst#go_binary
 .. _go_context: go/toolchains.rst#go_context
 .. _go_download_sdk: go/toolchains.rst#go_download_sdk
-.. _go_embed_data: go/extras.rst#go_embed_data
+.. _go_embed_data: go/extras.md#go_embed_data
 .. _go_host_sdk: go/toolchains.rst#go_host_sdk
 .. _go_library: go/core.rst#go_library
 .. _go_local_sdk: go/toolchains.rst#go_local_sdk
@@ -76,7 +76,7 @@ Announcements
   Release
   `v0.29.0 <https://github.com/bazelbuild/rules_go/releases/tag/v0.29.0>`_
   is now available. This enables `nogo` analyzers to depend on `go_library` rules,
-  removes the `rules_cc` dependency, adds automatic target detection to gopackagesdriver, 
+  removes the `rules_cc` dependency, adds automatic target detection to gopackagesdriver,
   and fixes some cgo-related bugs. See the release notes for details.
 2021-07-07
   Release
@@ -140,7 +140,7 @@ Documentation
   * `go_toolchain`_
   * `go_context`_
 
-* `Extra rules <go/extras.rst>`_
+* `Extra rules <go/extras.md>`_
 
   * `go_embed_data`_
 

WORKSPACE

@@ -140,3 +140,19 @@ local_repository(
     name = "runfiles_remote_test",
     path = "tests/core/runfiles/runfiles_remote_test",
 )
+
+# For API doc generation
+# This is a dev dependency, users should not need to install it
+# so we declare it in the WORKSPACE
+http_archive(
+    name = "io_bazel_stardoc",
+    sha256 = "c9794dcc8026a30ff67cf7cf91ebe245ca294b20b071845d12c192afe243ad72",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz",
+        "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz",
+    ],
+)
+
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+
+stardoc_repositories()

docs/BUILD.bazel

@@ -0,0 +1,50 @@
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+
+_DOC_SRCS = {
+    "//extras:embed_data": "extras.md",
+}
+
+[
+    stardoc(
+        name = out.replace(".md", "_docgen"),
+        out = out,
+        input = input + ".bzl",
+        deps = [input],
+    )
+    for [
+        input,
+        out,
+    ] in _DOC_SRCS.items()
+]
+
+[
+    diff_test(
+        name = "check_" + out,
+        failure_message = "Please run \"bazel run //docs:update\"",
+        # Source file
+        file1 = "//go:" + out,
+        # Output from stardoc rule above
+        file2 = out,
+    )
+    for out in _DOC_SRCS.values()
+]
+
+write_file(
+    name = "gen_update",
+    out = "update.sh",
+    content = [
+        "#!/bin/sh",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+    ] + [
+        "cp -fv bazel-bin/docs/{0} go/{0}".format(out)
+        for out in _DOC_SRCS.values()
+    ],
+)
+
+sh_binary(
+    name = "update",
+    srcs = ["update.sh"],
+    data = _DOC_SRCS.values(),
+)

extras/BUILD.bazel

@@ -1,5 +1,7 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
+exports_files(["embed_data.bzl"])
+
 filegroup(
     name = "all_rules",
     srcs = glob(["*.bzl"]) + ["//go/private:all_rules"],

extras/embed_data.bzl

@@ -12,13 +12,62 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""embed_data.bzl provides the go_embed_data rule for embedding data in go files"""
+"""
+  [gazelle rule]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule
+  [golang/mock]: https://github.com/golang/mock
+  [gomock_rule]: https://github.com/jmhodges/bazel_gomock
+  [core go rules]: core.rst
+
+# Extra rules
+
+This is a collection of helper rules. These are not core to building a go binary, but are supplied
+to make life a little easier.
+
+## Contents
+- [gazelle](#gazelle)
+- [gomock](#gomock)
+- [go_embed_data](#go_embed_data)
+
+## Additional resources
+- [gazelle rule]
+- [golang/mock]
+- [gomock_rule]
+- [core go rules]
+
+------------------------------------------------------------------------
+
+gazelle
+-------
+
+This rule has moved. See [gazelle rule] in the Gazelle repository.
+
+gomock
+------
+
+This rule allows you to generate mock interfaces with mockgen (from [golang/mock]) which can be useful for certain testing scenarios. See [gomock_rule] in the gomock repository.
+"""
 
 load(
     "@io_bazel_rules_go//go/private:context.bzl",  #TODO: This ought to be def
     "go_context",
 )
 
+_DOC = """`go_embed_data` generates a .go file that contains data from a file or a
+list of files. It should be consumed in the srcs list of one of the
+[core go rules].
+
+Before using `go_embed_data`, you must add the following snippet to your
+WORKSPACE:
+
+``` bzl
+load("@io_bazel_rules_go//extras:embed_data_deps.bzl", "go_embed_data_dependencies")
+
+go_embed_data_dependencies()
+```
+
+`go_embed_data` accepts the attributes listed below.
+"""
+
 def _go_embed_data_impl(ctx):
     go = go_context(ctx)
     if ctx.attr.src and ctx.attr.srcs:
@@ -80,14 +129,36 @@ def _go_embed_data_impl(ctx):
 
 go_embed_data = rule(
     implementation = _go_embed_data_impl,
+    doc = _DOC,
     attrs = {
-        "package": attr.string(),
-        "var": attr.string(default = "Data"),
-        "src": attr.label(allow_single_file = True),
-        "srcs": attr.label_list(allow_files = True),
-        "flatten": attr.bool(),
-        "unpack": attr.bool(),
-        "string": attr.bool(),
+        "package": attr.string(
+            doc = "Go package name for the generated .go file.",
+        ),
+        "var": attr.string(
+            default = "Data",
+            doc = "Name of the variable that will contain the embedded data.",
+        ),
+        "src": attr.label(
+            allow_single_file = True,
+            doc = """A single file to embed. This cannot be used at the same time as `srcs`.
+            The generated file will have a variable of type `[]byte` or `string` with the contents of this file.""",
+        ),
+        "srcs": attr.label_list(
+            allow_files = True,
+            doc = """A list of files to embed. This cannot be used at the same time as `src`.
+            The generated file will have a variable of type `map[string][]byte` or `map[string]string` with the contents
+            of each file. The map keys are relative paths of the files from the repository root. Keys for files in external
+            repositories will be prefixed with `"external/repo/"` where "repo" is the name of the external repository.""",
+        ),
+        "flatten": attr.bool(
+            doc = "If `True` and `srcs` is used, map keys are file base names instead of relative paths.",
+        ),
+        "unpack": attr.bool(
+            doc = "If `True`, sources are treated as archives and their contents will be stored. Supported formats are `.zip` and `.tar`",
+        ),
+        "string": attr.bool(
+            doc = "If `True`, the embedded data will be stored as `string` instead of `[]byte`.",
+        ),
         "_embed": attr.label(
             default = "@io_bazel_rules_go//go/tools/builders:embed",
             executable = True,
@@ -99,4 +170,4 @@ go_embed_data = rule(
     },
     toolchains = ["@io_bazel_rules_go//go:toolchain"],
 )
-# See go/extras.rst#go_embed_data for full documentation.
+# See go/extras.md#go_embed_data for full documentation.

go/BUILD.bazel

@@ -1,5 +1,7 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
+exports_files(["extras.md"])
+
 filegroup(
     name = "all_files",
     testonly = True,

go/extras.md

@@ -0,0 +1,76 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+
+  [gazelle rule]: https://github.com/bazelbuild/bazel-gazelle#bazel-rule
+  [golang/mock]: https://github.com/golang/mock
+  [gomock_rule]: https://github.com/jmhodges/bazel_gomock
+  [core go rules]: core.rst
+
+# Extra rules
+
+This is a collection of helper rules. These are not core to building a go binary, but are supplied
+to make life a little easier.
+
+## Contents
+- [gazelle](#gazelle)
+- [gomock](#gomock)
+- [go_embed_data](#go_embed_data)
+
+## Additional resources
+- [gazelle rule]
+- [golang/mock]
+- [gomock_rule]
+- [core go rules]
+
+------------------------------------------------------------------------
+
+gazelle
+-------
+
+This rule has moved. See [gazelle rule] in the Gazelle repository.
+
+gomock
+------
+
+This rule allows you to generate mock interfaces with mockgen (from [golang/mock]) which can be useful for certain testing scenarios. See [gomock_rule] in the gomock repository.
+
+
+<a id="#go_embed_data"></a>
+
+## go_embed_data
+
+<pre>
+go_embed_data(<a href="#go_embed_data-name">name</a>, <a href="#go_embed_data-flatten">flatten</a>, <a href="#go_embed_data-package">package</a>, <a href="#go_embed_data-src">src</a>, <a href="#go_embed_data-srcs">srcs</a>, <a href="#go_embed_data-string">string</a>, <a href="#go_embed_data-unpack">unpack</a>, <a href="#go_embed_data-var">var</a>)
+</pre>
+
+`go_embed_data` generates a .go file that contains data from a file or a
+list of files. It should be consumed in the srcs list of one of the
+[core go rules].
+
+Before using `go_embed_data`, you must add the following snippet to your
+WORKSPACE:
+
+``` bzl
+load("@io_bazel_rules_go//extras:embed_data_deps.bzl", "go_embed_data_dependencies")
+
+go_embed_data_dependencies()
+```
+
+`go_embed_data` accepts the attributes listed below.
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="go_embed_data-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="go_embed_data-flatten"></a>flatten |  If <code>True</code> and <code>srcs</code> is used, map keys are file base names instead of relative paths.   | Boolean | optional | False |
+| <a id="go_embed_data-package"></a>package |  Go package name for the generated .go file.   | String | optional | "" |
+| <a id="go_embed_data-src"></a>src |  A single file to embed. This cannot be used at the same time as <code>srcs</code>.             The generated file will have a variable of type <code>[]byte</code> or <code>string</code> with the contents of this file.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="go_embed_data-srcs"></a>srcs |  A list of files to embed. This cannot be used at the same time as <code>src</code>.             The generated file will have a variable of type <code>map[string][]byte</code> or <code>map[string]string</code> with the contents             of each file. The map keys are relative paths of the files from the repository root. Keys for files in external             repositories will be prefixed with <code>"external/repo/"</code> where "repo" is the name of the external repository.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
+| <a id="go_embed_data-string"></a>string |  If <code>True</code>, the embedded data will be stored as <code>string</code> instead of <code>[]byte</code>.   | Boolean | optional | False |
+| <a id="go_embed_data-unpack"></a>unpack |  If <code>True</code>, sources are treated as archives and their contents will be stored. Supported formats are <code>.zip</code> and <code>.tar</code>   | Boolean | optional | False |
+| <a id="go_embed_data-var"></a>var |  Name of the variable that will contain the embedded data.   | String | optional | "Data" |
+
+