generalize scripts to generate documentation

the boilerplate for accessing runfiles turned out to be not needed.

from now on one can just add targets or filenames for generating
documentation and checking that the generated files are up to date under
version control.

docs/BUILD.bazel

@@ -1,4 +1,4 @@
-load("stardoc.bzl", "stardoc")
+load("stardoc.bzl", "compare_files", "copy_files", "stardoc")
 
 stardoc(
     name = "nixpkgs",
@@ -93,19 +93,24 @@ genrule(
     toolchains = ["@rules_sh//sh/posix:make_variables"],
 )
 
-sh_test(
+compare_files(
     name = "check-readme",
-    srcs = ["check-readme.sh"],
     data = [
-        "README.md",
-        "//:README.md",
+        ("README.md", "//:README.md"),
+        ("core/README.md", "@rules_nixpkgs_core//:README.md"),
     ],
-    deps = ["@bazel_tools//tools/bash/runfiles"],
+    error_message = """
+    The project README is not up-to-date.
+    Please update it using the following command.
+
+    bazel run //docs:update-readme
+    """,
 )
 
-sh_binary(
+copy_files(
     name = "update-readme",
-    srcs = ["update-readme.sh"],
-    data = ["README.md", "core/README.md"],
-    deps = ["@bazel_tools//tools/bash/runfiles"],
+    data = [
+        "README.md",
+        "core/README.md",
+    ],
 )

docs/compare-files.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# compare contents of pairs of files passed as command line arguments.
+# print error message (set in `$errormsg` environment variable) and exit if any
+# pair does not have equal contents.
+while (($#)); do
+  if ! cmp -s "$1" "$2"; then
+    echo "$errormsg"
+    exit 1
+  fi
+  shift; shift
+done

docs/copy-files.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+while (($#)); do
+  cp "$1" "$BUILD_WORKSPACE_DIRECTORY/$2"
+  shift; shift
+done

docs/stardoc.bzl

@@ -21,3 +21,30 @@ def stardoc(
         rule_template = rule_template,
         **kwargs
     )
+
+def copy_files(name, data):
+    """copy list of files to workspace root"""
+    native.sh_binary(
+        name = name,
+        srcs = ["copy-files.sh"],
+        args = ["$(location {}) {}".format(f, f) for f in data],
+        data = data,
+    )
+
+def compare_files(name, data, error_message=""):
+    """
+    compare pairs of files for content equality.
+    print error message if a pair does not match.
+    """
+
+    # flatten pairs, as there is no meaningful way to work with anything but
+    # strings in `bash`
+    data = [f for pair in data for f in pair]
+    print(data)
+    native.sh_test(
+        name = name,
+        srcs = ["compare-files.sh"],
+        args = ["$(location {})".format(f) for f in data],
+        data = data,
+        env = {"errormsg" : error_message},
+    )