docs: enforce that api docs are up-to-date

Previously we just suggested you run a shell script to update, but there was no clue when that was needed in a PR

Author: alexeagle

CONTRIBUTING.md

@@ -43,15 +43,14 @@ merged.
 
 ### Documentation
 
-To regenerate the content under the `docs/` directory, run this script in the
-repository root:
+To regenerate the content under the `docs/` directory, run this command:
 
 ```shell
-./update_docs.sh
+bazel run //docs:update
 ```
 
 This needs to be done whenever the docstrings in the corresponding .bzl files
-are changed; see `docs/BUILD`.
+are changed; a test failure will remind you to run this command when needed.
 
 ### Precompiled tools
 

docs/BUILD

@@ -12,17 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-###############################################################################
-# To regenerate documentation, run the top-level update_docs.sh script.       #
-###############################################################################
-
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+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")
 
 package(default_visibility = ["//visibility:public"])
 
 licenses(["notice"])  # Apache 2.0
 
+_DOCS = {
+    "packaging": "//docs:packaging-docs",
+    "pip": "//docs:pip-docs",
+    "python": "//docs:core-docs",
+    "whl": "//docs:whl-docs",
+}
+
 # We define these bzl_library targets here rather than in the //python package
 # because they're only used for doc generation. This way, we avoid requiring
 # our users to depend on Skylib.
@@ -68,7 +73,7 @@ bzl_library(
 
 stardoc(
     name = "core-docs",
-    out = "python.md",
+    out = "python.md_",
     input = "//python:defs.bzl",
     deps = [":defs"],
 )
@@ -79,7 +84,7 @@ stardoc(
 
 stardoc(
     name = "pip-docs",
-    out = "pip.md",
+    out = "pip.md_",
     input = "//python:pip.bzl",
     deps = [
         ":bazel_repo_tools",
@@ -90,12 +95,40 @@ stardoc(
 
 stardoc(
     name = "whl-docs",
-    out = "whl.md",
+    out = "whl.md_",
     input = "//python:whl.bzl",
 )
 
 stardoc(
     name = "packaging-docs",
-    out = "packaging.md",
+    out = "packaging.md_",
     input = "//python:packaging.bzl",
 )
+
+[
+    diff_test(
+        name = "check_" + k,
+        failure_message = "Please run:   bazel run //docs:update",
+        file1 = k + ".md",
+        file2 = k + ".md_",
+    )
+    for k in _DOCS.keys()
+]
+
+write_file(
+    name = "gen_update",
+    out = "update.sh",
+    content = [
+        "#!/usr/bin/env bash",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+    ] + [
+        "cp -fv bazel-bin/docs/{0}.md_ docs/{0}.md".format(k)
+        for k in _DOCS.keys()
+    ],
+)
+
+sh_binary(
+    name = "update",
+    srcs = ["update.sh"],
+    data = _DOCS.values(),
+)

internal_deps.bzl

@@ -11,10 +11,11 @@ def rules_python_internal_deps():
     maybe(
         http_archive,
         name = "bazel_skylib",
-        strip_prefix = "bazel-skylib-1.0.2",
-        url = "https://github.com/bazelbuild/bazel-skylib/archive/1.0.2.zip",
-        type = "zip",
-        sha256 = "64ad2728ccdd2044216e4cec7815918b7bb3bb28c95b7e9d951f9d4eccb07625",
+        sha256 = "c6966ec828da198c5d9adbaa94c05e3a1c7f21bd012a0b29ba8ddbccb2c93b0d",
+        urls = [
+            "https://github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz",
+            "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.1.1/bazel-skylib-1.1.1.tar.gz",
+        ],
     )
 
     maybe(