Merge pull request #137303 from cockroachdb/blathers/backport-release…

…-24.3-137135

release-24.3: ci: check that generated documentation is up-to-date

build/github/build.sh

@@ -48,3 +48,59 @@ bazel build \
     //pkg/cmd/cockroach-short //pkg/cmd/cockroach \
     //pkg/cmd/cockroach-sql $GEOS_TARGET $EXTRA_TARGETS
 
+# We don't have to exercise the checks below on every configuration, only
+# bother with Linux.
+if [ "$CONFIG" != "crosslinux" ]
+then
+    exit 0
+fi
+
+# This is going to be very noisy if we don't disbale this logging.
+set +x
+BAZEL_BIN=$(bazel info bazel-bin --config "$CONFIG")
+FAILED=
+# Ensure all generated docs are byte-for-byte identical with the checkout.
+for FILE in $(find $BAZEL_BIN/docs -type f)
+do
+    RESULT=$(diff $FILE ${FILE##$BAZEL_BIN/})
+    if [[ ! $? -eq 0 ]]
+    then
+        echo "File $FILE does not match with checked-in version. Got diff:"
+        echo "$RESULT"
+        echo "Run './dev generate docs'"
+        FAILED=1
+    fi
+done
+# Ensure the generated docs are inclusive of what we have in tree: list all
+# generated files in a few subdirectories and make sure they're all in the
+# build output.
+for FILE in $(ls docs/generated/http/*.md | xargs -n1 basename)
+do
+    if [[ ! -f $BAZEL_BIN/docs/generated/http/$FILE ]]
+    then
+        echo "File $BAZEL_BIN/docs/generated/http/$FILE does not exist as a generated artifact; it is checked in under `docs/generated/http`, but is not being built. Is docs/generated/http/BUILD.bazel up-to-date?"
+        FAILED=1
+    fi
+done
+for FILE in $(ls docs/generated/sql/*.md | xargs -n1 basename)
+do
+    if [[ ! -f $BAZEL_BIN/docs/generated/sql/$FILE ]]
+    then
+        echo "File $BAZEL_BIN/docs/generated/sql/$FILE does not exist as a generated artifact; it is checked in under `docs/generated/sql`, but is not being built. Is docs/generated/sql/BUILD.bazel up-to-date?"
+        FAILED=1
+    fi
+done
+for FILE in $(ls docs/generated/sql/bnf/*.bnf | xargs -n1 basename)
+do
+    if [[ ! -f $BAZEL_BIN/docs/generated/sql/bnf/$FILE ]]
+    then
+        echo "File $BAZEL_BIN/docs/generated/sql/bnf/$FILE does not exist as a generated artifact; it is checked in under `docs/generated/sql/bnf`, but is not being built. Is docs/generated/sql/bnf/BUILD.bazel up-to-date?"
+        FAILED=1
+    fi
+done
+
+if [[ ! -z "$FAILED" ]]
+then
+    echo 'Generated files do not match! Are the checked-in generated files up-to-date?'
+    exit 1
+fi

docs/generated/sql/bnf/BUILD.bazel

@@ -73,6 +73,7 @@ FILES = [
     "backup",
     "backup_options",
     "begin_transaction",
+    "begin_stmt",
     "call",
     "cancel_all_jobs",
     "cancel_job",

pkg/gen/bnf.bzl

@@ -72,6 +72,7 @@ BNF_SRCS = [
     "//docs/generated/sql/bnf:analyze_stmt.bnf",
     "//docs/generated/sql/bnf:backup.bnf",
     "//docs/generated/sql/bnf:backup_options.bnf",
+    "//docs/generated/sql/bnf:begin_stmt.bnf",
     "//docs/generated/sql/bnf:begin_transaction.bnf",
     "//docs/generated/sql/bnf:call.bnf",
     "//docs/generated/sql/bnf:cancel_all_jobs.bnf",

pkg/gen/diagrams.bzl

@@ -72,6 +72,7 @@ DIAGRAMS_SRCS = [
     "//docs/generated/sql/bnf:analyze.html",
     "//docs/generated/sql/bnf:backup.html",
     "//docs/generated/sql/bnf:backup_options.html",
+    "//docs/generated/sql/bnf:begin.html",
     "//docs/generated/sql/bnf:begin_transaction.html",
     "//docs/generated/sql/bnf:call.html",
     "//docs/generated/sql/bnf:cancel.html",

pkg/gen/docs.bzl

@@ -85,6 +85,7 @@ DOCS_SRCS = [
     "//docs/generated/sql/bnf:analyze_stmt.bnf",
     "//docs/generated/sql/bnf:backup.bnf",
     "//docs/generated/sql/bnf:backup_options.bnf",
+    "//docs/generated/sql/bnf:begin_stmt.bnf",
     "//docs/generated/sql/bnf:begin_transaction.bnf",
     "//docs/generated/sql/bnf:call.bnf",
     "//docs/generated/sql/bnf:cancel_all_jobs.bnf",