Added generated test examples to change_point docs

Author: craigtaverner

docs/reference/query-languages/esql/README.md

@@ -79,9 +79,78 @@ These are also generated as part of the unit tests described above.
 
 ### Adding a new command
 
-When adding a new command, for example adding the `CHANGE_POINT` comamand, do the following:
+When adding a new command, for example adding the `CHANGE_POINT` command, do the following:
 1. Create a new file in the `_snippets/commands/layout` directory with the name of the command, for example `change_point.md`.
 2. Add the content for the command to the file. See other files in this directory for examples.
 3. Add the command to the list in `_snippets/lists/processing-commands-md`.
 4. Add an include directive to the `commands/processing-commands.md` file to include the new command.
 5. Add tested examples to the `_snippets/commands/examples` directory. See below for details.
+
+### Adding examples to commands
+
+When adding tested examples to a command, for example adding an example to the `CHANGE_POINT` command, do the following:
+* Make sure you have an example in an appropriate csv-spec file in the `x-pack/plugin/esql/qa/testFixtures/src/main/resources/` directory.
+* Make sure the example has a tag that is unique in that file, and matches the intent of the test, or the docs reason for including that test.
+* If you only want to show the query, and no results, then do not tag the results table,
+  otherwise tag the results table with a tag that has the same name as the query tag, but with the suffix `-result`.
+* Create a file with the name of the tag in a subdirectory with the name of the csv-spec file
+  in the `_snippets/commands/examples` directory. While you could add the content to that file, it is not necessary, merely that the file exists
+* Run the test `CommandsDocsTests` in the `x-pack/plugin/esql` module to generate the content.
+
+For example, we tag the following test in change_point.csv-spec:
+
+```
+example for docs
+required_capability: change_point
+
+// tag::changePointForDocs[]
+ROW key=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]
+| MV_EXPAND key
+| EVAL value = CASE(key<13, 0, 42)
+| CHANGE_POINT value ON key
+| WHERE type IS NOT NULL
+// end::changePointForDocs[]
+;
+
+// tag::changePointForDocs-result[]
+key:integer | value:integer | type:keyword | pvalue:double
+13          | 42            | step_change  | 0.0
+// end::changePointForDocs-result[]
+;
+```
+
+Then we create the file `_snippets/commands/examples/change_point.csv-spec/changePointForDocs.md` with the content:
+```
+This should be overwritten
+```
+
+Then we run the test `CommandsDocsTests` in the `x-pack/plugin/esql` module to generate the content.
+
+Now the content of the changePointForDocs.md file should have been updated:
+
+```
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+\```esql
+ROW key=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]
+| MV_EXPAND key
+| EVAL value = CASE(key<13, 0, 42)
+| CHANGE_POINT value ON key
+| WHERE type IS NOT NULL
+\```
+
+| key:integer | value:integer | type:keyword | pvalue:double |
+| --- | --- | --- | --- |
+| 13 | 42 | step_change | 0.0 |
+```
+
+Finally include this file in the `CHANGE_POINT` command file `_snippets/commands/layout/change_point.md`:
+
+```
+**Examples**
+
+The following example shows the detection of a step change:
+
+:::{include} ../examples/change_point.csv-spec/changePointForDocs.md
+:::
+```

docs/reference/query-languages/esql/_snippets/commands/examples/change_point.csv-spec/changePointForDocs.md

@@ -0,0 +1,13 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+```esql
+ROW key=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]
+| MV_EXPAND key
+| EVAL value = CASE(key<13, 0, 42)
+| CHANGE_POINT value ON key
+| WHERE type IS NOT NULL
+```
+
+| key:integer | value:integer | type:keyword | pvalue:double |
+| --- | --- | --- | --- |
+| 13 | 42 | step_change | 0.0 |

docs/reference/query-languages/esql/_snippets/commands/layout/change_point.md

@@ -50,15 +50,5 @@ There must be at least 22 values for change point detection. Fewer than 1,000 is
 
 The following example shows the detection of a step change:
 
-```
-ROW key = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]
-| MV_EXPAND key
-| EVAL value = CASE(key<13, 0, 42)
-| CHANGE_POINT value ON key
-| WHERE type IS NOT NULL
-;
-```
-
-| key:integer | value:integer | type:keyword | pvalue:double |
-|-------------|---------------|--------------|---------------|
-| 13          | 42            | step_change  | 0.0           |
+:::{include} ../examples/change_point.csv-spec/changePointForDocs.md
+:::

x-pack/plugin/esql/qa/testFixtures/src/main/resources/change_point.csv-spec

@@ -1203,13 +1203,17 @@ true        | 1             | null         | null
 example for docs
 required_capability: change_point
 
+// tag::changePointForDocs[]
 ROW key=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]
 | MV_EXPAND key
 | EVAL value = CASE(key<13, 0, 42)
 | CHANGE_POINT value ON key
 | WHERE type IS NOT NULL
+// end::changePointForDocs[]
 ;
 
+// tag::changePointForDocs-result[]
 key:integer | value:integer | type:keyword | pvalue:double
 13          | 42            | step_change  | 0.0          
+// end::changePointForDocs-result[]
 ;