Add first stardoc API docgen target (#598)

Author: alexeagle

WORKSPACE

@@ -17,3 +17,18 @@ swift_rules_extra_dependencies()
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
 
 bazel_skylib_workspace()
+
+# For API doc generation
+# This is a dev dependency, users should not need to install it
+# so we declare it in the WORKSPACE
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "io_bazel_stardoc",
+    patches = [],
+    sha256 = "f89bda7b6b696c777b5cf0ba66c80d5aa97a6701977d43789a9aee319eef71e8",
+    strip_prefix = "stardoc-d93ee5347e2d9c225ad315094507e018364d5a67",
+    urls = [
+        "https://github.com/bazelbuild/stardoc/archive/d93ee5347e2d9c225ad315094507e018364d5a67.tar.gz",
+    ],
+)

doc/BUILD.bazel

@@ -0,0 +1,45 @@
+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")
+
+_RULES_SYMBOLS = [
+    "swift_binary",
+    "swift_c_module",
+    "swift_grpc_library",
+    "swift_import",
+    "swift_library",
+    "swift_module_alias",
+    "swift_proto_library",
+    "swift_test",
+]
+
+write_file(
+    name = "gen_header",
+    out = "header.vm",
+    content = [
+        "<!-- Generated with Stardoc, Do Not Edit! -->",
+        "",
+        "${moduleDocstring}",
+        "On this page:",
+        "",
+    ] + ["  * [{0}](#{0})".format(r) for r in _RULES_SYMBOLS] + [
+        "",
+    ],
+)
+
+stardoc(
+    name = "doc",
+    out = "swift.md",
+    header_template = ":header.vm",
+    input = "//swift:swift.bzl",
+    symbol_names = _RULES_SYMBOLS,
+    deps = ["//swift"],
+)
+
+# To make this test pass, run
+# bazel build doc:all && cp bazel-bin/doc/swift.md doc/rules.md
+diff_test(
+    name = "test",
+    file1 = "swift.md",
+    file2 = "rules.md",
+)