ESQL: Fail build docs aren't up to date (#131739)

Adds a new behavior to the esql build we enable in CI that, instead of
generating the docs, asserts that they are already up to date.

Author: nik9000

docs/reference/query-languages/esql/_snippets/functions/description/md5.md

@@ -94,37 +94,55 @@ interface Injected {
 }
 
 tasks.named("test").configure {
-  if (buildParams.ci == false) {
-    systemProperty 'generateDocs', true
-    def injected = project.objects.newInstance(Injected)
-    // Define the folder to delete and recreate
-    def tempDir = file("build/testrun/test/temp/esql")
-    def commandsExamplesFile = new File(tempDir, "commands.examples")
-    // Find all matching .md files for commands examples
-    def mdFiles = fileTree("${rootDir}/docs/reference/query-languages/esql/_snippets/commands/examples/") {
-      include("**/*.csv-spec/*.md")
+  def injected = project.objects.newInstance(Injected)
+  // Define the folder to delete and recreate
+  def tempDir = file("build/testrun/test/temp/esql")
+  def commandsExamplesFile = new File(tempDir, "commands.examples")
+  // Find all matching .md files for commands examples
+  def mdFiles = fileTree("${rootDir}/docs/reference/query-languages/esql/_snippets/commands/examples/") {
+    include("**/*.csv-spec/*.md")
+  }
+  def esqlDocFolder = file("${rootDir}/docs/reference/query-languages/esql").toPath()
+  def imagesDocFolder = file("${esqlDocFolder}/images")
+  def snippetsDocFolder = file("${esqlDocFolder}/_snippets")
+  def kibanaDocFolder = file("${esqlDocFolder}/kibana")
+  File imagesFolder = file("build/testrun/test/temp/esql/images")
+  File snippetsFolder = file("build/testrun/test/temp/esql/_snippets")
+  File kibanaFolder = file("build/testrun/test/temp/esql/kibana")
+
+  doFirst {
+    injected.fs.delete {
+      it.delete(tempDir)
     }
-    doFirst {
-      injected.fs.delete {
-        it.delete(tempDir)
-      }
-      // Re-create this folder so we can save a table of generated examples to extract from csv-spec tests
-      tempDir.mkdirs() // Recreate the folder
+    // Re-create this folder so we can save a table of generated examples to extract from csv-spec tests
+    tempDir.mkdirs() // Recreate the folder
 
-      // Write directory name and filename of each .md file to the output file
-      commandsExamplesFile.withWriter { writer ->
-        mdFiles.each { file ->
-          writer.writeLine("${file.parentFile.name}/${file.name}")
-        }
+    // Write directory name and filename of each .md file to the output file
+    commandsExamplesFile.withWriter { writer ->
+      mdFiles.each { file ->
+        writer.writeLine("${file.parentFile.name}/${file.name}")
       }
-      println "File 'commands.examples' created with ${mdFiles.size()} example specifications from csv-spec files."
     }
-    File imagesFolder = file("build/testrun/test/temp/esql/images")
-    File snippetsFolder = file("build/testrun/test/temp/esql/_snippets")
-    File kibanaFolder = file("build/testrun/test/temp/esql/kibana")
-    def imagesDocFolder = file("${rootDir}/docs/reference/query-languages/esql/images")
-    def snippetsDocFolder = file("${rootDir}/docs/reference/query-languages/esql/_snippets")
-    def kibanaDocFolder = file("${rootDir}/docs/reference/query-languages/esql/kibana")
+    println "File 'commands.examples' created with ${mdFiles.size()} example specifications from csv-spec files."
+    if (buildParams.ci) {
+      injected.fs.sync {
+        from snippetsDocFolder
+        into snippetsFolder
+      }
+      injected.fs.sync {
+        from imagesDocFolder
+        into imagesFolder
+      }
+      injected.fs.sync {
+        from kibanaDocFolder
+        into kibanaFolder
+      }
+    }
+  }
+  if (buildParams.ci) {
+    systemProperty 'generateDocs', 'assert'
+  } else {
+    systemProperty 'generateDocs', 'write'
     def snippetsTree = fileTree(snippetsFolder).matching {
       include "**/types/*.md"  // Recursively include all types/*.md files (effectively counting functions and operators)
     }
@@ -229,9 +247,19 @@ tasks.named("test").configure {
 // This is similar to the test task above, but needed for the LookupJoinTypesIT which runs in the internalClusterTest task
 // and generates a types table for the LOOKUP JOIN command. It is possible in future we might have move tests that do this.
 tasks.named("internalClusterTest").configure {
-  if (buildParams.ci == false) {
-    systemProperty 'generateDocs', true
-    def injected = project.objects.newInstance(Injected)
+  def injected = project.objects.newInstance(Injected)
+  File snippetsFolder = file("build/testrun/internalClusterTest/temp/esql/_snippets")
+  def snippetsDocFolder = file("${rootDir}/docs/reference/query-languages/esql/_snippets")
+  if (buildParams.ci) {
+    systemProperty 'generateDocs', 'assert'
+    doFirst {
+      injected.fs.sync {
+        from snippetsDocFolder
+        into snippetsFolder
+      }
+    }
+  } else {
+    systemProperty 'generateDocs', 'write'
     // Define the folder to delete and recreate
     def tempDir = file("build/testrun/internalClusterTest/temp/esql")
     doFirst {
@@ -241,8 +269,6 @@ tasks.named("internalClusterTest").configure {
       // Re-create this folder so we can save a table of generated examples to extract from csv-spec tests
       tempDir.mkdirs() // Recreate the folder
     }
-    File snippetsFolder = file("build/testrun/internalClusterTest/temp/esql/_snippets")
-    def snippetsDocFolder = file("${rootDir}/docs/reference/query-languages/esql/_snippets")
     def snippetsTree = fileTree(snippetsFolder).matching {
       include "**/types/*.md"  // Recursively include all types/*.md files (effectively counting functions and operators)
     }

docs/reference/query-languages/esql/_snippets/functions/examples/knn.md

@@ -768,6 +768,9 @@ private boolean isValidDataType(DataType dataType) {
     }
 
     private static void saveJoinTypes(Supplier<Map<List<DataType>, DataType>> signatures) throws Exception {
+        if (System.getProperty("generateDocs") == null) {
+            return;
+        }
         ArrayList<EsqlFunctionRegistry.ArgSignature> args = new ArrayList<>();
         args.add(new EsqlFunctionRegistry.ArgSignature("field from the left index", null, null, false, false));
         args.add(new EsqlFunctionRegistry.ArgSignature("field from the lookup index", null, null, false, false));
@@ -776,7 +779,8 @@ private static void saveJoinTypes(Supplier<Map<List<DataType>, DataType>> signat
             LookupJoinTypesIT.class,
             null,
             args,
-            signatures
+            signatures,
+            DocsV3Support.callbacksFromSystemProperty()
         );
         docs.renderDocs();
     }