Update docgen to be a pair of diff_test and sh_binary to accept new content (#658)

.bazelci/config.yaml

@@ -165,10 +165,8 @@ tasks:
     name: Docs
     platform: ubuntu2004
     working_directory: docs
-    build_targets:
+    test_targets:
       - //...
-    run_targets:
-      - //:test_docs
   min_supported_version:
     name: "Minimum Supported Version"
     bazel: "3.7.0"

docs/BUILD.bazel

@@ -1,4 +1,5 @@
-load("@bazel_skylib//rules:build_test.bzl", "build_test")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 
 genrule(
@@ -20,24 +21,22 @@ stardoc(
     deps = ["@rules_foreign_cc//:bzl_srcs"],
 )
 
-build_test(
-    name = "docs_build_test",
-    targets = [
-        ":docs",
-    ],
-    visibility = ["//visibility:public"],
+# When this test fails, run
+# (cd docs; bazel run :generate_docs)
+diff_test(
+    name = "test",
+    file1 = ":docs",
+    file2 = "README.md",
 )
 
-genrule(
+write_file(
     name = "generate_docs_src",
-    srcs = [":docs"],
-    outs = ["generate_docs.sh"],
-    cmd = """cat << EOF > $@
-#!/bin/bash
-set -euo pipefail
-cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/README.md
-EOF
-""",
+    out = "update.sh",
+    content = [
+        "#!/usr/bin/env bash",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+        "cp -fv bazel-bin/docs.md README.md",
+    ],
 )
 
 sh_binary(
@@ -45,8 +44,3 @@ sh_binary(
     srcs = [":generate_docs_src"],
     data = [":docs"],
 )
-
-sh_binary(
-    name = "test_docs",
-    srcs = ["test_docs.sh"],
-)

docs/README.md

@@ -1,3 +1,4 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
 # Rules Foreign CC
 
 - [boost_build](#boost_build)

docs/gen_header.sh

@@ -25,6 +25,7 @@ TABLE_OF_CONTENTS=$(grep "=" "$1" \
 )
 
 cat << EOF > "$2"
+<!-- Generated with Stardoc, Do Not Edit! -->
 # Rules Foreign CC
 
 ${TABLE_OF_CONTENTS}