Restructure change_point docs to new structure

Author: craigtaverner

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

@@ -3,10 +3,23 @@ The static content exists in this directory and can be edited by hand.
 However, the sub-directories `_snippets`, `images` and `kibana` contain mostly
 generated content.
 
+## Static content
+
+The root `esql` directory and the following two subdirectories contain static content:
+* `commands` - contains the static content for the ES|QL commands.
+  This content will typically contain mostly include directives for content in the `_snippets` or `images` directories.
+* `functions-operators` - contains the static content for the ES|QL functions and operators.
+  Again this will contain mostly include directives for content in the `_snippets` or `images` directories.
+
+## Mixed static and generated content
+
+Generated content is created by running the ESQL tests in the `x-pack/plugin/esql` module.
+It will be written into three subdirectories of the `esql` directory:
+
 ### _snippets
 
-In `_snippets` there are files that can be included within other files
-using the [File Inclusion](https://elastic.github.io/docs-builder/syntax/file_inclusion/)
+In `_snippets` there are files that can be included within other files using the
+[File Inclusion](https://elastic.github.io/docs-builder/syntax/file_inclusion/)
 feature of the Elastic Docs V3 system.
 Most, but not all, files in this directory are generated.
 In particular the directories `_snippets/functions/*` and `_snippets/operators/*`
@@ -34,6 +47,19 @@ To regenerate the files for all functions run all of ESQL's tests using gradle:
 ./gradlew :x-pack:plugin:esql:test
 ```
 
+#### Commands
+
+The `_snippets/commands` directory contains the content for the ES|QL commands.
+There are two subdirectories, one static and one generated:
+* `layout` - contains the static content for the ES|QL commands.
+  The files in this directory are the main content for the documentation for the commands.
+  They are not generated, and so this is the primary place to edit the content, or add new commands.
+* `examples` - contains the generated content for the ES|QL commands.
+  The files in this directory are generated from the test `CommandsDocsTests` in the `x-pack/plugin/esql` module.
+  The structure of the subdirectories mimics the csv-spec files and test tags used in the tests.
+
+Including generated examples in the command documentation is done by using the include directive.
+
 ### images
 
 The `images` directory contains `functions` and `operators` sub-directories with
@@ -48,3 +74,14 @@ The `kibana` directory contains `definition` and `docs` sub-directories that are
 * `kibana/docs` - the inline docs for kibana
 
 These are also generated as part of the unit tests described above.
+
+## Tutorials
+
+### Adding a new command
+
+When adding a new command, for example adding the `CHANGE_POINT` comamand, 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.

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

@@ -0,0 +1,64 @@
+## `CHANGE_POINT` [esql-change_point]
+
+::::{warning}
+This functionality is in technical preview and may be
+changed or removed in a future release. Elastic will work to fix any
+issues, but features in technical preview are not subject to the support
+SLA of official GA features.
+::::
+
+`CHANGE_POINT` detects spikes, dips, and change points in a metric.
+
+**Syntax**
+
+```esql
+CHANGE_POINT value [ON key] [AS type_name, pvalue_name]
+```
+
+**Parameters**
+
+`value`
+:   The column with the metric in which you want to detect a change point.
+
+`key`
+:   The column with the key to order the values by. If not specified, `@timestamp` is used.
+
+`type_name`
+:   The name of the output column with the change point type. If not specified, `type` is used.
+
+`pvalue_name`
+:   The name of the output column with the p-value that indicates how extreme the change point is. If not specified, `pvalue` is used.
+
+**Description**
+
+`CHANGE_POINT` detects spikes, dips, and change points in a metric. The command adds columns to
+the table with the change point type and p-value, that indicates how extreme the change point is
+(lower values indicate greater changes).
+
+The possible change point types are:
+* `dip`: a significant dip occurs at this change point
+* `distribution_change`: the overall distribution of the values has changed significantly
+* `spike`: a significant spike occurs at this point
+* `step_change`: the change indicates a statistically significant step up or down in value distribution
+* `trend_change`: there is an overall trend change occurring at this point
+
+::::{note}
+There must be at least 22 values for change point detection. Fewer than 1,000 is preferred.
+::::
+
+**Examples**
+
+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           |

docs/reference/query-languages/esql/_snippets/lists/processing-commands.md

@@ -1,3 +1,4 @@
+* [`CHANGE_POINT`](../../commands/processing-commands.md#esql-change_point)
 * [`DISSECT`](../../commands/processing-commands.md#esql-dissect)
 * [`DROP`](../../commands/processing-commands.md#esql-drop)
 * [`ENRICH`](../../commands/processing-commands.md#esql-enrich)

docs/reference/query-languages/esql/commands/processing-commands.md

@@ -17,6 +17,9 @@ mapped_pages:
 :::{include} ../_snippets/lists/processing-commands.md
 :::
 
+:::{include} ../_snippets/commands/layout/change_point.md
+:::
+
 :::{include} ../_snippets/commands/layout/dissect.md
 :::