Support depthOffset in MD docs headings for nesting functions

craigtaverner · craigtaverner · commit f63d65b60d87 · 2025-04-17T11:03:57.000+02:00
diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/st_xmax.md b/docs/reference/query-languages/esql/_snippets/functions/layout/st_xmax.md
diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/st_xmin.md b/docs/reference/query-languages/esql/_snippets/functions/layout/st_xmin.md
diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/st_ymax.md b/docs/reference/query-languages/esql/_snippets/functions/layout/st_ymax.md
diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/st_ymin.md b/docs/reference/query-languages/esql/_snippets/functions/layout/st_ymin.md
diff --git a/docs/reference/query-languages/esql/_snippets/lists/spatial-functions.md b/docs/reference/query-languages/esql/_snippets/lists/spatial-functions.md
@@ -6,19 +6,19 @@
 * [`ST_X`](../../functions-operators/spatial-functions.md#esql-st_x)
 * [`ST_Y`](../../functions-operators/spatial-functions.md#esql-st_y)
 * [preview] [`ST_ENVELOPE`](../../functions-operators/spatial-functions.md#esql-st_envelope)
-* [preview] [`ST_XMAX`](../../functions-operators/spatial-functions.md#esql-st_xmax)
-* [preview] [`ST_XMIN`](../../functions-operators/spatial-functions.md#esql-st_xmin)
-* [preview] [`ST_YMAX`](../../functions-operators/spatial-functions.md#esql-st_ymax)
-* [preview] [`ST_YMIN`](../../functions-operators/spatial-functions.md#esql-st_ymin)
+  * [preview] [`ST_XMAX`](../../functions-operators/spatial-functions.md#esql-st_xmax)
+  * [preview] [`ST_XMIN`](../../functions-operators/spatial-functions.md#esql-st_xmin)
+  * [preview] [`ST_YMAX`](../../functions-operators/spatial-functions.md#esql-st_ymax)
+  * [preview] [`ST_YMIN`](../../functions-operators/spatial-functions.md#esql-st_ymin)
 * [preview] [`ST_GEOTILE`](../../functions-operators/spatial-functions.md#esql-st_geotile)
+  * [preview] [`ST_GEOTILE_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_string)
+  * [preview] [`ST_GEOTILE_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_long)
+  * [preview] [`ST_GEOTILE_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_geoshape)
 * [preview] [`ST_GEOHEX`](../../functions-operators/spatial-functions.md#esql-st_geohex)
+  * [preview] [`ST_GEOHEX_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_string)
+  * [preview] [`ST_GEOHEX_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_long)
+  * [preview] [`ST_GEOHEX_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_geoshape)
 * [preview] [`ST_GEOHASH`](../../functions-operators/spatial-functions.md#esql-st_geohash)
-* [preview] [`ST_GEOTILE_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_string)
-* [preview] [`ST_GEOHEX_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_string)
-* [preview] [`ST_GEOHASH_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_string)
-* [preview] [`ST_GEOTILE_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_long)
-* [preview] [`ST_GEOHEX_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_long)
-* [preview] [`ST_GEOHASH_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_long)
-* [preview] [`ST_GEOTILE_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_geoshape)
-* [preview] [`ST_GEOHEX_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_geoshape)
-* [preview] [`ST_GEOHASH_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_geoshape)
+  * [preview] [`ST_GEOHASH_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_string)
+  * [preview] [`ST_GEOHASH_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_long)
+  * [preview] [`ST_GEOHASH_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_geoshape)
diff --git a/docs/reference/query-languages/esql/functions-operators/spatial-functions.md b/docs/reference/query-languages/esql/functions-operators/spatial-functions.md
@@ -51,34 +51,34 @@ mapped_pages:
 :::{include} ../_snippets/functions/layout/st_geotile.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohex.md
+:::{include} ../_snippets/functions/layout/st_geotile_to_string.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohash.md
+:::{include} ../_snippets/functions/layout/st_geotile_to_long.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geotile_to_string.md
+:::{include} ../_snippets/functions/layout/st_geotile_to_geoshape.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohex_to_string.md
+:::{include} ../_snippets/functions/layout/st_geohex.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohash_to_string.md
+:::{include} ../_snippets/functions/layout/st_geohex_to_string.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geotile_to_long.md
+:::{include} ../_snippets/functions/layout/st_geohex_to_long.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohex_to_long.md
+:::{include} ../_snippets/functions/layout/st_geohex_to_geoshape.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohash_to_long.md
+:::{include} ../_snippets/functions/layout/st_geohash.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geotile_to_geoshape.md
+:::{include} ../_snippets/functions/layout/st_geohash_to_string.md
 :::
 
-:::{include} ../_snippets/functions/layout/st_geohex_to_geoshape.md
+:::{include} ../_snippets/functions/layout/st_geohash_to_long.md
 :::
 
 :::{include} ../_snippets/functions/layout/st_geohash_to_geoshape.md
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java
@@ -70,6 +70,11 @@
      */
     String appendix() default "";
 
+    /**
+     * The heading depth of this function in the docs, relative to the normal depth of functions.
+     */
+    int depthOffset() default 0;
+
     /**
      * The position the function can appear in the language.
      */
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StXMax.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StXMax.java
@@ -45,7 +45,8 @@ public class StXMax extends UnaryScalarFunction {
         returnType = "double",
         description = "Extracts the maximum value of the `x` coordinates from the supplied geometry.\n"
             + "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `longitude` value.",
-        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
+        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
+        depthOffset = 1  // So this appears as a subsection of ST_ENVELOPE
     )
     public StXMax(
         Source source,
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StXMin.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StXMin.java
@@ -45,7 +45,8 @@ public class StXMin extends UnaryScalarFunction {
         returnType = "double",
         description = "Extracts the minimum value of the `x` coordinates from the supplied geometry.\n"
             + "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `longitude` value.",
-        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
+        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
+        depthOffset = 1  // So this appears as a subsection of ST_ENVELOPE
     )
     public StXMin(
         Source source,
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StYMax.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StYMax.java
@@ -45,7 +45,8 @@ public class StYMax extends UnaryScalarFunction {
         returnType = "double",
         description = "Extracts the maximum value of the `y` coordinates from the supplied geometry.\n"
             + "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `latitude` value.",
-        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
+        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
+        depthOffset = 1  // So this appears as a subsection of ST_ENVELOPE
     )
     public StYMax(
         Source source,
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StYMin.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StYMin.java
@@ -45,7 +45,8 @@ public class StYMin extends UnaryScalarFunction {
         returnType = "double",
         description = "Extracts the minimum value of the `y` coordinates from the supplied geometry.\n"
             + "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `latitude` value.",
-        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
+        examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
+        depthOffset = 1  // So this appears as a subsection of ST_ENVELOPE
     )
     public StYMin(
         Source source,
diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java
@@ -536,7 +536,7 @@ private void renderDocs(FunctionDefinition definition) throws IOException {
             }
             boolean hasExamples = renderExamples(info);
             boolean hasAppendix = renderAppendix(info.appendix());
-            renderFullLayout(info.preview(), info.appliesTo(), hasExamples, hasAppendix, hasFunctionOptions);
+            renderFullLayout(info, hasExamples, hasAppendix, hasFunctionOptions);
             renderKibanaInlineDocs(name, null, info);
             renderKibanaFunctionDefinition(name, null, info, description.args(), description.variadic());
         }
@@ -627,16 +627,12 @@ private void appendLifeCycleAndVersion(StringBuilder appliesToText, FunctionAppl
             }
         }
 
-        private void renderFullLayout(
-            boolean preview,
-            FunctionAppliesTo[] functionAppliesTos,
-            boolean hasExamples,
-            boolean hasAppendix,
-            boolean hasFunctionOptions
-        ) throws IOException {
+        private void renderFullLayout(FunctionInfo info, boolean hasExamples, boolean hasAppendix, boolean hasFunctionOptions)
+            throws IOException {
+            String headingMarkdown = "#".repeat(2 + info.depthOffset());
             StringBuilder rendered = new StringBuilder(
                 DOCS_WARNING + """
-                    ## `$UPPER_NAME$` [esql-$NAME$]
+                    $HEAD$ `$UPPER_NAME$` [esql-$NAME$]
                     $PREVIEW_CALLOUT$
                     **Syntax**
 
@@ -645,10 +641,11 @@ private void renderFullLayout(
                     :class: text-center
                     :::
 
-                    """.replace("$NAME$", name)
+                    """.replace("$HEAD$", headingMarkdown)
+                    .replace("$NAME$", name)
                     .replace("$CATEGORY$", category)
                     .replace("$UPPER_NAME$", name.toUpperCase(Locale.ROOT))
-                    .replace("$PREVIEW_CALLOUT$", makePreviewText(preview, functionAppliesTos))
+                    .replace("$PREVIEW_CALLOUT$", makePreviewText(info.preview(), info.appliesTo()))
             );
             for (String section : new String[] { "parameters", "description", "types" }) {
                 rendered.append(addInclude(section));
@@ -777,6 +774,11 @@ public String appendix() {
                     return orig.appendix().replace(baseName, name);
                 }
 
+                @Override
+                public int depthOffset() {
+                    return orig.depthOffset();
+                }
+
                 @Override
                 public FunctionType type() {
                     return orig.type();
