Improve update-reference-docs UX

Signed-off-by: James Munnelly <james@munnelly.eu>

hack/BUILD.bazel

@@ -212,18 +212,25 @@ sh_test(
 sh_binary(
     name = "update-reference-docs",
     srcs = ["update-reference-docs.sh"],
+    args = [
+        "$(location @//docs/generated/reference/generate)",
+    ],
     data = [
-        "//docs/generated/reference/generate",
+        "@//docs/generated/reference/generate",
     ],
 )
 
 sh_test(
     name = "verify-reference-docs",
     srcs = ["verify-reference-docs.sh"],
+    args = [
+        "$(location :update-reference-docs)",
+        "$(location @//docs/generated/reference/generate)",
+    ],
     data = [
-        "//docs/generated/reference:output",
-        "//docs/generated/reference/generate",
-        "//hack:update-reference-docs.sh",
+        ":update-reference-docs",
+        "@//docs/generated/reference:output",
+        "@//docs/generated/reference/generate",
     ],
 )
 

hack/update-reference-docs.sh

@@ -17,18 +17,34 @@ set -o errexit
 set -o nounset
 set -o pipefail
 
-# This script should be run via `bazel run //hack:update-reference-docs`
-REPO_ROOT=${BUILD_WORKSPACE_DIRECTORY:-"$(cd "$(dirname "$0")" && pwd -P)"/..}
-SCRIPT_RUNFILES="${runfiles:-$(pwd)}"
-cd "${REPO_ROOT}"
+if [[ -n "${BUILD_WORKSPACE_DIRECTORY:-}" ]]; then # Running inside bazel
+  echo "Regenerate API reference documentation..." >&2
+elif ! command -v bazel &>/dev/null; then
+  echo "Install bazel at https://bazel.build" >&2
+  exit 1
+else
+  (
+    set -o xtrace
+    bazel run @com_github_jetstack_cert_manager//hack:update-reference-docs
+  )
+  exit 0
+fi
 
+generated_tarball=$(realpath "$1")
+
+cd "$BUILD_WORKSPACE_DIRECTORY"
+output_path="docs/generated/reference/output/reference/api-docs"
 # The final directory path to store the generated output data
-OUTPUT_DIR="$(cd "${REPO_ROOT}/docs/generated/reference/output/reference/api-docs" 2> /dev/null && pwd -P)"
+output_dir="$BUILD_WORKSPACE_DIRECTORY/$output_path"
 
-TMP_OUTPUT="$(mktemp -d)"
+# create a temporary directory to extract the generated reference docs tarball to
+tmp_output="$(mktemp -d)"
+# extract the generated docs tarball
+tar -C "${tmp_output}" -xf "$generated_tarball"
 
-tar -C "${TMP_OUTPUT}" -xf "${SCRIPT_RUNFILES}/docs/generated/reference/generate/generated.tar.gz"
+# clean up the output directory
+rm -Rf "${output_dir}"
 
-rm -Rf "${OUTPUT_DIR}"
-mkdir -p "${OUTPUT_DIR}"
-mv "${TMP_OUTPUT}"/* "${OUTPUT_DIR}"
+# recreate the output directory and move extracted content to it
+mkdir -p "${output_dir}"
+mv "${tmp_output}"/* "${output_dir}"

hack/verify-reference-docs.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-
 # Copyright 2019 The Jetstack cert-manager contributors.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,41 +13,46 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-set -o errexit
 set -o nounset
+set -o errexit
 set -o pipefail
 
-RULE_NAME="reference-docs"
-
-SCRIPT_ROOT=$(dirname "${BASH_SOURCE}")/..
-
-_tmp="$(mktemp -d)"
-DIFFROOT="${SCRIPT_ROOT}/"
-
-cleanup() {
-  rm -rf "${_tmp}"
-}
-trap "cleanup" EXIT SIGINT
-
-# Create a fake GOPATH
-export GOPATH="${_tmp}"
-TMP_DIFFROOT="${GOPATH}/src/github.com/jetstack/cert-manager"
-
-mkdir -p "${TMP_DIFFROOT}"
-rsync -avvL "${DIFFROOT}"/ "${TMP_DIFFROOT}" >/dev/null
-
-export runfiles="$(pwd)"
-cd "${TMP_DIFFROOT}"
-export BUILD_WORKSPACE_DIRECTORY="$(pwd)"
-"hack/update-${RULE_NAME}.sh"
-
-echo "diffing ${DIFFROOT} against freshly generated ${RULE_NAME}"
-ret=0
-diff --exclude=__main__ -Naupr "${DIFFROOT}/docs/generated/reference/output" "${TMP_DIFFROOT}/docs/generated/reference/output" || ret=$?
-if [[ $ret -eq 0 ]]
-then
-  echo "${DIFFROOT} up to date."
+if [[ -n "${TEST_WORKSPACE:-}" ]]; then # Running inside bazel
+  echo "Checking generated API reference documentation for changes..." >&2
+elif ! command -v bazel &>/dev/null; then
+  echo "Install bazel at https://bazel.build" >&2
+  exit 1
 else
-  echo "${DIFFROOT} is out of date. Please run 'bazel run //hack:update-${RULE_NAME}'"
+  (
+    set -o xtrace
+    bazel test --test_output=streamed //hack:verify-reference-docs
+  )
+  exit 0
+fi
+
+compare_to=$(realpath "docs/generated/reference/output")
+
+tmpfiles=$TEST_TMPDIR/files
+
+(
+  mkdir -p "$tmpfiles"
+  rm -f bazel-*
+  cp -aL "." "$tmpfiles"
+  export BUILD_WORKSPACE_DIRECTORY=$tmpfiles
+  "$@"
+)
+
+# Avoid diff -N so we handle empty files correctly
+diff=$(diff -upr \
+  -x ".git" \
+  -x "bazel-*" \
+  -x "_output" \
+  "." "$tmpfiles" 2>/dev/null || true)
+
+if [[ -n "${diff}" ]]; then
+  echo "${diff}" >&2
+  echo >&2
+  echo "ERROR: generated API reference documentation changed. Update with ./hack/update-reference-docs.sh" >&2
   exit 1
 fi
+echo "SUCCESS: generated API reference documentation up-to-date"