Skip to content

Commit f63d65b

Browse files
craigtavernercraigtaverner
committed
Support depthOffset in MD docs headings for nesting functions
1 parent 72bd227 commit f63d65b

File tree

12 files changed

+53
-42
lines changed

12 files changed

+53
-42
lines changed

‎docs/reference/query-languages/esql/_snippets/functions/layout/st_xmax.md

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/query-languages/esql/_snippets/functions/layout/st_xmin.md

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/query-languages/esql/_snippets/functions/layout/st_ymax.md

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/query-languages/esql/_snippets/functions/layout/st_ymin.md

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/query-languages/esql/_snippets/lists/spatial-functions.md

+13-13
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,19 @@
66
* [`ST_X`](../../functions-operators/spatial-functions.md#esql-st_x)
77
* [`ST_Y`](../../functions-operators/spatial-functions.md#esql-st_y)
88
* [preview] [`ST_ENVELOPE`](../../functions-operators/spatial-functions.md#esql-st_envelope)
9-
* [preview] [`ST_XMAX`](../../functions-operators/spatial-functions.md#esql-st_xmax)
10-
* [preview] [`ST_XMIN`](../../functions-operators/spatial-functions.md#esql-st_xmin)
11-
* [preview] [`ST_YMAX`](../../functions-operators/spatial-functions.md#esql-st_ymax)
12-
* [preview] [`ST_YMIN`](../../functions-operators/spatial-functions.md#esql-st_ymin)
9+
* [preview] [`ST_XMAX`](../../functions-operators/spatial-functions.md#esql-st_xmax)
10+
* [preview] [`ST_XMIN`](../../functions-operators/spatial-functions.md#esql-st_xmin)
11+
* [preview] [`ST_YMAX`](../../functions-operators/spatial-functions.md#esql-st_ymax)
12+
* [preview] [`ST_YMIN`](../../functions-operators/spatial-functions.md#esql-st_ymin)
1313
* [preview] [`ST_GEOTILE`](../../functions-operators/spatial-functions.md#esql-st_geotile)
14+
* [preview] [`ST_GEOTILE_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_string)
15+
* [preview] [`ST_GEOTILE_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_long)
16+
* [preview] [`ST_GEOTILE_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_geoshape)
1417
* [preview] [`ST_GEOHEX`](../../functions-operators/spatial-functions.md#esql-st_geohex)
18+
* [preview] [`ST_GEOHEX_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_string)
19+
* [preview] [`ST_GEOHEX_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_long)
20+
* [preview] [`ST_GEOHEX_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_geoshape)
1521
* [preview] [`ST_GEOHASH`](../../functions-operators/spatial-functions.md#esql-st_geohash)
16-
* [preview] [`ST_GEOTILE_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_string)
17-
* [preview] [`ST_GEOHEX_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_string)
18-
* [preview] [`ST_GEOHASH_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_string)
19-
* [preview] [`ST_GEOTILE_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_long)
20-
* [preview] [`ST_GEOHEX_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_long)
21-
* [preview] [`ST_GEOHASH_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_long)
22-
* [preview] [`ST_GEOTILE_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geotile_to_geoshape)
23-
* [preview] [`ST_GEOHEX_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohex_to_geoshape)
24-
* [preview] [`ST_GEOHASH_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_geoshape)
22+
* [preview] [`ST_GEOHASH_TO_STRING`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_string)
23+
* [preview] [`ST_GEOHASH_TO_LONG`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_long)
24+
* [preview] [`ST_GEOHASH_TO_GEOSHAPE`](../../functions-operators/spatial-functions.md#esql-st_geohash_to_geoshape)

‎docs/reference/query-languages/esql/functions-operators/spatial-functions.md

+10-10
Original file line numberDiff line numberDiff line change
@@ -51,34 +51,34 @@ mapped_pages:
5151
:::{include} ../_snippets/functions/layout/st_geotile.md
5252
:::
5353

54-
:::{include} ../_snippets/functions/layout/st_geohex.md
54+
:::{include} ../_snippets/functions/layout/st_geotile_to_string.md
5555
:::
5656

57-
:::{include} ../_snippets/functions/layout/st_geohash.md
57+
:::{include} ../_snippets/functions/layout/st_geotile_to_long.md
5858
:::
5959

60-
:::{include} ../_snippets/functions/layout/st_geotile_to_string.md
60+
:::{include} ../_snippets/functions/layout/st_geotile_to_geoshape.md
6161
:::
6262

63-
:::{include} ../_snippets/functions/layout/st_geohex_to_string.md
63+
:::{include} ../_snippets/functions/layout/st_geohex.md
6464
:::
6565

66-
:::{include} ../_snippets/functions/layout/st_geohash_to_string.md
66+
:::{include} ../_snippets/functions/layout/st_geohex_to_string.md
6767
:::
6868

69-
:::{include} ../_snippets/functions/layout/st_geotile_to_long.md
69+
:::{include} ../_snippets/functions/layout/st_geohex_to_long.md
7070
:::
7171

72-
:::{include} ../_snippets/functions/layout/st_geohex_to_long.md
72+
:::{include} ../_snippets/functions/layout/st_geohex_to_geoshape.md
7373
:::
7474

75-
:::{include} ../_snippets/functions/layout/st_geohash_to_long.md
75+
:::{include} ../_snippets/functions/layout/st_geohash.md
7676
:::
7777

78-
:::{include} ../_snippets/functions/layout/st_geotile_to_geoshape.md
78+
:::{include} ../_snippets/functions/layout/st_geohash_to_string.md
7979
:::
8080

81-
:::{include} ../_snippets/functions/layout/st_geohex_to_geoshape.md
81+
:::{include} ../_snippets/functions/layout/st_geohash_to_long.md
8282
:::
8383

8484
:::{include} ../_snippets/functions/layout/st_geohash_to_geoshape.md

‎x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java

+5
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,11 @@
7070
*/
7171
String appendix() default "";
7272

73+
/**
74+
* The heading depth of this function in the docs, relative to the normal depth of functions.
75+
*/
76+
int depthOffset() default 0;
77+
7378
/**
7479
* The position the function can appear in the language.
7580
*/

‎x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StXMax.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ public class StXMax extends UnaryScalarFunction {
4545
returnType = "double",
4646
description = "Extracts the maximum value of the `x` coordinates from the supplied geometry.\n"
4747
+ "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `longitude` value.",
48-
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
48+
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
49+
depthOffset = 1 // So this appears as a subsection of ST_ENVELOPE
4950
)
5051
public StXMax(
5152
Source source,

‎x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StXMin.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ public class StXMin extends UnaryScalarFunction {
4545
returnType = "double",
4646
description = "Extracts the minimum value of the `x` coordinates from the supplied geometry.\n"
4747
+ "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `longitude` value.",
48-
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
48+
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
49+
depthOffset = 1 // So this appears as a subsection of ST_ENVELOPE
4950
)
5051
public StXMin(
5152
Source source,

‎x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StYMax.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ public class StYMax extends UnaryScalarFunction {
4545
returnType = "double",
4646
description = "Extracts the maximum value of the `y` coordinates from the supplied geometry.\n"
4747
+ "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the maximum `latitude` value.",
48-
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
48+
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
49+
depthOffset = 1 // So this appears as a subsection of ST_ENVELOPE
4950
)
5051
public StYMax(
5152
Source source,

‎x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/spatial/StYMin.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ public class StYMin extends UnaryScalarFunction {
4545
returnType = "double",
4646
description = "Extracts the minimum value of the `y` coordinates from the supplied geometry.\n"
4747
+ "If the geometry is of type `geo_point` or `geo_shape` this is equivalent to extracting the minimum `latitude` value.",
48-
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max")
48+
examples = @Example(file = "spatial_shapes", tag = "st_x_y_min_max"),
49+
depthOffset = 1 // So this appears as a subsection of ST_ENVELOPE
4950
)
5051
public StYMin(
5152
Source source,

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

+13-11
Original file line numberDiff line numberDiff line change
@@ -536,7 +536,7 @@ private void renderDocs(FunctionDefinition definition) throws IOException {
536536
}
537537
boolean hasExamples = renderExamples(info);
538538
boolean hasAppendix = renderAppendix(info.appendix());
539-
renderFullLayout(info.preview(), info.appliesTo(), hasExamples, hasAppendix, hasFunctionOptions);
539+
renderFullLayout(info, hasExamples, hasAppendix, hasFunctionOptions);
540540
renderKibanaInlineDocs(name, null, info);
541541
renderKibanaFunctionDefinition(name, null, info, description.args(), description.variadic());
542542
}
@@ -627,16 +627,12 @@ private void appendLifeCycleAndVersion(StringBuilder appliesToText, FunctionAppl
627627
}
628628
}
629629

630-
private void renderFullLayout(
631-
boolean preview,
632-
FunctionAppliesTo[] functionAppliesTos,
633-
boolean hasExamples,
634-
boolean hasAppendix,
635-
boolean hasFunctionOptions
636-
) throws IOException {
630+
private void renderFullLayout(FunctionInfo info, boolean hasExamples, boolean hasAppendix, boolean hasFunctionOptions)
631+
throws IOException {
632+
String headingMarkdown = "#".repeat(2 + info.depthOffset());
637633
StringBuilder rendered = new StringBuilder(
638634
DOCS_WARNING + """
639-
## `$UPPER_NAME$` [esql-$NAME$]
635+
$HEAD$ `$UPPER_NAME$` [esql-$NAME$]
640636
$PREVIEW_CALLOUT$
641637
**Syntax**
642638
@@ -645,10 +641,11 @@ private void renderFullLayout(
645641
:class: text-center
646642
:::
647643
648-
""".replace("$NAME$", name)
644+
""".replace("$HEAD$", headingMarkdown)
645+
.replace("$NAME$", name)
649646
.replace("$CATEGORY$", category)
650647
.replace("$UPPER_NAME$", name.toUpperCase(Locale.ROOT))
651-
.replace("$PREVIEW_CALLOUT$", makePreviewText(preview, functionAppliesTos))
648+
.replace("$PREVIEW_CALLOUT$", makePreviewText(info.preview(), info.appliesTo()))
652649
);
653650
for (String section : new String[] { "parameters", "description", "types" }) {
654651
rendered.append(addInclude(section));
@@ -777,6 +774,11 @@ public String appendix() {
777774
return orig.appendix().replace(baseName, name);
778775
}
779776

777+
@Override
778+
public int depthOffset() {
779+
return orig.depthOffset();
780+
}
781+
780782
@Override
781783
public FunctionType type() {
782784
return orig.type();

0 commit comments

Comments
 (0)