Add diff_test asserting that docs are up-to-date

it prints a convenient 'bazel run' command to update them, replacing the shell script

Follow-up to #297 (comment)

.bazelci/presubmit.yml

@@ -46,6 +46,7 @@ tasks:
     # TODO(laszlocsomor): remove "--test_env=LOCALAPPDATA" after
     # https://github.com/bazelbuild/bazel/issues/7761 is fixed
     - "--test_env=LOCALAPPDATA"
+    - "--test_tag_filters=-no-bazelci-windows"
 
   ubuntu1804_last_green:
     name: "Last Green Bazel"
@@ -93,5 +94,6 @@ tasks:
     # TODO(laszlocsomor): remove "--test_env=LOCALAPPDATA" after
     # https://github.com/bazelbuild/bazel/issues/7761 is fixed
     - "--test_env=LOCALAPPDATA"
+    - "--test_tag_filters=-no-bazelci-windows"
 
 buildifier: latest

docs/BUILD

@@ -1,137 +1,73 @@
 load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc")
+load("//rules:diff_test.bzl", "diff_test")
+load("//rules:write_file.bzl", "write_file")
 
 licenses(["notice"])
 
-# Note that due to a bug in Bazel 0.22.0, these targets cannot be built without
-# the --incompatible_remap_main_repo flag.
-stardoc(
-    name = "build_test_docs",
-    out = "build_test_doc_gen.md",
-    input = "//rules:build_test.bzl",
-    deps = ["//rules:build_test"],
-)
-
-stardoc(
-    name = "analysis_test_docs",
-    out = "analysis_test_doc_gen.md",
-    input = "//rules:analysis_test.bzl",
-)
-
-stardoc(
-    name = "collections_docs",
-    out = "collections_doc_gen.md",
-    input = "//lib:collections.bzl",
-    deps = ["//lib:collections"],
-)
-
-stardoc(
-    name = "dicts_docs",
-    out = "dicts_doc_gen.md",
-    input = "//lib:dicts.bzl",
-    deps = ["//lib:dicts"],
-)
-
-stardoc(
-    name = "partial_docs",
-    out = "partial_doc_gen.md",
-    input = "//lib:partial.bzl",
-    deps = ["//lib:partial"],
-)
-
-stardoc(
-    name = "paths_docs",
-    out = "paths_doc_gen.md",
-    input = "//lib:paths.bzl",
-    deps = ["//lib:paths"],
-)
-
-stardoc(
-    name = "selects_docs",
-    out = "selects_doc_gen.md",
-    input = "//lib:selects.bzl",
-    deps = ["//lib:selects"],
-)
-
-stardoc(
-    name = "new_sets_docs",
-    out = "new_sets_doc_gen.md",
-    input = "//lib:new_sets.bzl",
-    deps = ["//lib:new_sets"],
-)
-
-stardoc(
-    name = "shell_docs",
-    out = "shell_doc_gen.md",
-    input = "//lib:shell.bzl",
-    deps = ["//lib:shell"],
-)
-
-stardoc(
-    name = "structs_docs",
-    out = "structs_doc_gen.md",
-    input = "//lib:structs.bzl",
-    deps = ["//lib:structs"],
-)
-
-stardoc(
-    name = "types_docs",
-    out = "types_doc_gen.md",
-    input = "//lib:types.bzl",
-    deps = ["//lib:types"],
-)
-
-stardoc(
-    name = "unittest_docs",
-    out = "unittest_doc_gen.md",
-    input = "//lib:unittest.bzl",
-    deps = ["//lib:unittest"],
-)
-
-stardoc(
-    name = "versions_docs",
-    out = "versions_doc_gen.md",
-    input = "//lib:versions.bzl",
-    deps = ["//lib:versions"],
-)
-
-stardoc(
-    name = "copy_file_docs",
-    out = "copy_file_doc_gen.md",
-    input = "//rules:copy_file.bzl",
-    deps = ["//rules:copy_file"],
-)
-
-stardoc(
-    name = "write_file_docs",
-    out = "write_file_doc_gen.md",
-    input = "//rules:write_file.bzl",
-    deps = ["//rules:write_file"],
-)
-
-stardoc(
-    name = "diff_test_docs",
-    out = "diff_test_doc_gen.md",
-    input = "//rules:diff_test.bzl",
-    deps = ["//rules:diff_test"],
-)
-
-stardoc(
-    name = "native_binary_docs",
-    out = "native_binary_doc_gen.md",
-    input = "//rules:native_binary.bzl",
-    deps = ["//rules:native_binary"],
-)
-
-stardoc(
-    name = "run_binary_docs",
-    out = "run_binary_doc_gen.md",
-    input = "//rules:run_binary.bzl",
-    deps = ["//rules:run_binary"],
-)
-
-stardoc(
-    name = "common_settings_docs",
-    out = "common_settings_doc_gen.md",
-    input = "//rules:common_settings.bzl",
-    deps = ["//rules:common_settings"],
+_DOCS = {
+    "analysis_test": "//rules:analysis_test",
+    "build_test": "//rules:build_test",
+    "collections": "//lib:collections",
+    "common_settings": "//rules:common_settings",
+    "copy_file": "//rules:copy_file",
+    "dicts": "//lib:dicts",
+    "diff_test": "//rules:diff_test",
+    "native_binary": "//rules:native_binary",
+    "new_sets": "//lib:new_sets",
+    "partial": "//lib:partial",
+    "paths": "//lib:paths",
+    "run_binary": "//rules:run_binary",
+    "selects": "//lib:selects",
+    "shell": "//lib:shell",
+    "structs": "//lib:structs",
+    "types": "//lib:types",
+    "unittest": "//lib:unittest",
+    "versions": "//lib:versions",
+    "write_file": "//rules:write_file",
+}
+
+[
+    stardoc(
+        name = k + "_docs",
+        out = k + "_doc_gen.md",
+        input = v + ".bzl",
+        deps = [v],
+    )
+    for [
+        k,
+        v,
+    ] in _DOCS.items()
+]
+
+[
+    diff_test(
+        name = "test_" + s,
+        failure_message = "Please run bazel run //docs:update",
+        file1 = s + "_doc_gen.md",
+        file2 = s + "_doc.md",
+        # When run on Windows, stardoc produces CRLF line endings.
+        # Ideally this should be fixed in stardoc so that developers on
+        # Windows can update the documentation without causing edits to
+        # every line.
+        tags = ["no-bazelci-windows"],
+    )
+    for s in _DOCS.keys()
+]
+
+write_file(
+    name = "update_gen",
+    out = "update.sh",
+    content = [
+        "#!/bin/sh",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+    ] + [
+        "cp -fv bazel-bin/docs/{0}_doc_gen.md docs/{0}_doc.md".format(s)
+        for s in _DOCS.keys()
+    ],
+)
+
+sh_binary(
+    name = "update",
+    srcs = ["update.sh"],
+    data = [s + "_doc_gen.md" for s in _DOCS.keys()],
 )