ESQL: Only generate syntax diagrams locally

CI will skip building them. Lot's of CI machines don't have font support
so they can't generate these. But all local machine have a GUI so they
can.

Also, super-lazy initialize the font so CI don't bump into it by
accident.

Closes elastic#99018

docs/reference/esql/functions/types/ceil.asciidoc

@@ -1,6 +1,6 @@
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-arg1 | result
+n | result
 double | double
 integer | integer
 long | long

docs/reference/esql/functions/types/left.asciidoc

@@ -0,0 +1,5 @@
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+arg1 | arg2 | result
+keyword | integer | keyword
+|===

x-pack/plugin/esql/build.gradle

@@ -56,7 +56,11 @@ sourceSets.main.java {
 }
 
 tasks.getByName('test') {
-  dependsOn 'cleanGeneratedDocs'
+  if (BuildParams.isCi() == false) {
+    dependsOn 'cleanGeneratedDocs'
+    finalizedBy 'copyGeneratedDocs'
+    systemProperty 'generateDocs', true
+  }
 }
 
 tasks.register('cleanGeneratedDocs', Delete) {

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/package-info.java

@@ -123,8 +123,8 @@
  *         asciidoc ceremony to make the result look right in the rendered docs.
  *     </li>
  *     <li>
- *         Auto-generate a syntax diagram and a table with supported types by running
- *         {@code ./gradlew x-pack:plugin:esql:copyGeneratedDocs}
+ *         Generate a syntax diagram and a table with supported types by running the tests via
+ *         gradle: {@code ./gradlew x-pack:plugin:esql:test}
  *         The generated files can be found here
  *         {@code docs/reference/esql/functions/signature/myfunction.svg }
  *         and here

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java

@@ -845,6 +845,22 @@ private static Stream<DataType> representable() {
         return EsqlDataTypes.types().stream().filter(EsqlDataTypes::isRepresentable);
     }
 
+    @AfterClass
+    public static void renderSignature() throws IOException {
+        if (System.getProperty("generateDocs") == null) {
+            return;
+        }
+        FunctionDefinition definition = definition();
+        if (definition == null) {
+            LogManager.getLogger(getTestClass()).info("Skipping rendering signature because the function isn't registered");
+            return;
+        }
+
+        String rendered = RailRoadDiagram.functionSignature(definition);
+        LogManager.getLogger(getTestClass()).info("Writing function signature");
+        writeToTempDir("signature", rendered, "svg");
+    }
+
     /**
      * Unique signatures encountered by this test.
      * <p>
@@ -880,6 +896,9 @@ public void trackSignature() {
 
     @AfterClass
     public static void renderTypesTable() throws IOException {
+        if (System.getProperty("generateDocs") == null) {
+            return;
+        }
         FunctionDefinition definition = definition();
         if (definition == null) {
             LogManager.getLogger(getTestClass()).info("Skipping rendering types because the function isn't registered");

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/RailRoadDiagram.java

@@ -19,6 +19,7 @@
 import net.nextencia.rrdiagram.grammar.rrdiagram.RRElement;
 import net.nextencia.rrdiagram.grammar.rrdiagram.RRText;
 
+import org.elasticsearch.common.util.LazyInitializable;
 import org.elasticsearch.xpack.esql.plan.logical.show.ShowFunctions;
 import org.elasticsearch.xpack.ql.expression.function.FunctionDefinition;
 
@@ -40,9 +41,9 @@ public class RailRoadDiagram {
      * on whatever fonts you have installed. And, since the world can't agree
      * on fonts, that'd be chaos. So, instead, we load Roboto Mono.
      */
-    private static final Font FONT = loadFont().deriveFont(20.0F);
+    private static final LazyInitializable<Font, IOException> FONT = new LazyInitializable<>(() -> loadFont().deriveFont(20.0F));
 
-    static String functionSignature(FunctionDefinition definition) {
+    static String functionSignature(FunctionDefinition definition) throws IOException {
         List<Expression> expressions = new ArrayList<>();
         expressions.add(new SpecialSequence(definition.name().toUpperCase(Locale.ROOT)));
         expressions.add(new Syntax("("));
@@ -68,12 +69,12 @@ static String functionSignature(FunctionDefinition definition) {
 
         RRDiagramToSVG toSvg = new RRDiagramToSVG();
         toSvg.setSpecialSequenceShape(RRDiagramToSVG.BoxShape.RECTANGLE);
-        toSvg.setSpecialSequenceFont(FONT);
+        toSvg.setSpecialSequenceFont(FONT.getOrCompute());
 
         toSvg.setLiteralFillColor(toSvg.getSpecialSequenceFillColor());
-        toSvg.setLiteralFont(FONT);
+        toSvg.setLiteralFont(FONT.getOrCompute());
 
-        toSvg.setRuleFont(FONT);
+        toSvg.setRuleFont(FONT.getOrCompute());
         /*
          * "Tighten" the styles in the SVG so they beat the styles sitting in the
          * main page. We need this because we're embedding the SVG into the page.
@@ -143,7 +144,7 @@ public void addElement(String element) {
         }
     }
 
-    private static Font loadFont() {
+    private static Font loadFont() throws IOException {
         try {
             InputStream woff = RailRoadDiagram.class.getClassLoader()
                 .getResourceAsStream("META-INF/resources/webjars/fontsource__roboto-mono/4.5.7/files/roboto-mono-latin-400-normal.woff");
@@ -152,9 +153,7 @@ private static Font loadFont() {
             }
             return Font.createFont(Font.TRUETYPE_FONT, new WoffConverter().convertToTTFOutputStream(woff));
         } catch (FontFormatException e) {
-            throw new RuntimeException(e);
-        } catch (IOException e) {
-            throw new RuntimeException(e);
+            throw new IOException(e);
         }
     }
 }