Enable CI testing for docgen (bazelbuild#617)

.bazelci/presubmit.yml

@@ -25,6 +25,7 @@ x_defaults:
     test_flags: *linux_flags
     test_targets:
       - "--"
+      - "//doc/..."
       - "//examples/..."
       - "//test/..."
       - "-//examples/apple/..."

doc/BUILD.bazel

@@ -2,23 +2,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",
-]
+_DOC_SRCS = {
+    "aspects": [
+        "swift_usage_aspect",
+    ],
+    "providers": [
+        "SwiftInfo",
+        "SwiftToolchainInfo",
+        "SwiftProtoInfo",
+        "SwiftUsageInfo",
+    ],
+    "rules": [
+        "swift_binary",
+        "swift_c_module",
+        "swift_grpc_library",
+        "swift_import",
+        "swift_library",
+        "swift_module_alias",
+        "swift_proto_library",
+        "swift_test",
+    ],
+}
 
-_PROVIDERS_SYMBOLS = [
-    "SwiftInfo",
-    "SwiftToolchainInfo",
-    "SwiftProtoInfo",
-    "SwiftUsageInfo",
-]
+write_file(
+    name = "aspects_header",
+    out = "aspects_header.vm",
+    content = [
+        "<!-- Generated with Stardoc, Do Not Edit! -->",
+        "# Aspects",
+        "",
+        "The aspects described below are used within the build rule implementations.",
+        "Clients interested in writing custom rules that interface with the rules/provides",
+        "in this package might needs them to provide some of the same information.",
+        "",
+        "On this page:",
+        "",
+    ] + ["  * [{0}](#{0})".format(r) for r in _DOC_SRCS["aspects"]] + [
+        "",
+    ],
+)
 
 write_file(
     name = "rules_header",
@@ -29,7 +51,7 @@ write_file(
         "${moduleDocstring}",
         "On this page:",
         "",
-    ] + ["  * [{0}](#{0})".format(r) for r in _RULES_SYMBOLS] + [
+    ] + ["  * [{0}](#{0})".format(r) for r in _DOC_SRCS["rules"]] + [
         "",
     ],
 )
@@ -47,41 +69,53 @@ write_file(
         "",
         "On this page:",
         "",
-    ] + ["  * [{0}](#{0})".format(r) for r in _PROVIDERS_SYMBOLS] + [
+    ] + ["  * [{0}](#{0})".format(r) for r in _DOC_SRCS["providers"]] + [
         "",
     ],
 )
 
-stardoc(
-    name = "rules_doc",
-    out = "rules.md_",
-    header_template = ":rules_header.vm",
-    input = "//swift:swift.bzl",
-    symbol_names = _RULES_SYMBOLS,
-    deps = ["//swift"],
-)
+[
+    stardoc(
+        name = file + "_doc",
+        out = file + ".md_",
+        header_template = file + "_header.vm",
+        input = "//swift:swift.bzl",
+        symbol_names = symbols,
+        deps = ["//swift"],
+    )
+    for [
+        file,
+        symbols,
+    ] in _DOC_SRCS.items()
+]
 
-stardoc(
-    name = "providers_doc",
-    out = "providers.md_",
-    header_template = ":providers_header.vm",
-    input = "//swift:swift.bzl",
-    symbol_names = _PROVIDERS_SYMBOLS,
-    deps = ["//swift"],
-)
+# To make these tests pass, run
+# bazel run //doc:update
+[
+    diff_test(
+        name = "test_" + file,
+        file1 = file + ".md_",
+        file2 = file + ".md",
+    )
+    for file in _DOC_SRCS.keys()
+]
 
-# To make this test pass, run
-# bazel build doc:all && cp bazel-bin/doc/rules.md_ doc/rules.md
-diff_test(
-    name = "test_rules",
-    file1 = "rules.md_",
-    file2 = "rules.md",
+write_file(
+    name = "gen_update",
+    out = "update.sh",
+    content = [
+        "#!/usr/bin/env bash",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+    ] + [
+        "cp -fv bazel-bin/doc/{0}.md_ doc/{0}.md".format(
+            file,
+        )
+        for file in _DOC_SRCS.keys()
+    ],
 )
 
-# To make this test pass, run
-# bazel build doc:all && cp bazel-bin/doc/providers.md_ doc/providers.md
-diff_test(
-    name = "test_providers",
-    file1 = "providers.md_",
-    file2 = "providers.md",
+sh_binary(
+    name = "update",
+    srcs = ["update.sh"],
+    data = [file + ".md_" for file in _DOC_SRCS.keys()],
 )

doc/aspects.md

@@ -1,9 +1,6 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
 # Aspects
 
-<!-- Generated file, do not edit directly. -->
-
-
-
 The aspects described below are used within the build rule implementations.
 Clients interested in writing custom rules that interface with the rules/provides
 in this package might needs them to provide some of the same information.
@@ -12,11 +9,12 @@ On this page:
 
   * [swift_usage_aspect](#swift_usage_aspect)
 
-<a name="swift_usage_aspect"></a>
+<a id="#swift_usage_aspect"></a>
+
 ## swift_usage_aspect
 
-<pre style="white-space: normal">
-swift_usage_aspect()
+<pre>
+swift_usage_aspect(<a href="#swift_usage_aspect-name">name</a>)
 </pre>
 
 Collects information about how Swift is used in a dependency tree.
@@ -40,3 +38,20 @@ providers returned by `swift_library`) because the information is needed if
 Swift is used _anywhere_ in a dependency graph, even as dependencies of other
 language rules that wouldn't know how to propagate the Swift-specific providers.
 
+
+**ASPECT ATTRIBUTES**
+
+
+| Name | Type |
+| :------------- | :------------- |
+| deps| String |
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="swift_usage_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |   |
+
+

swift/internal/BUILD

@@ -146,6 +146,7 @@ bzl_library(
 
 bzl_library(
     name = "swift_binary_test",
+    srcs = ["swift_binary_test.bzl"],
     visibility = ["//swift:__subpackages__"],
     deps = [
         ":compiling",
@@ -227,6 +228,7 @@ bzl_library(
     visibility = ["//swift:__subpackages__"],
     deps = [
         ":attrs",
+        ":build_settings",
         ":compiling",
         ":feature_names",
         ":linking",