The ES|QL documentation is composed of static content and generated content.
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.

### _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/)
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/*`
contain subdirectories that are mostly generated:

* `description` - description of each function scraped from `@FunctionInfo#description`
* `examples` - examples of each function scraped from `@FunctionInfo#examples`
* `parameters` - description of each function's parameters scraped from `@Param`
* `signature` - railroad diagram of the syntax to invoke each function
* `types` - a table of each combination of support type for each parameter. These are generated from tests.
* `layout` - a fully generated description for each function

Most functions can use the generated docs generated in the `layout` directory.
If we need something more custom for the function we can make a file in this
directory that can `include::` any parts of the files above.

To regenerate the files for a function run its tests using gradle.
For example to generate docs for the `CASE` function:
```
./gradlew :x-pack:plugin:esql:test -Dtests.class='CaseTests'
```

To regenerate the files for all functions run all of ESQL's tests using gradle:
```
./gradlew :x-pack:plugin:esql:test
```

### images

The `images` directory contains `functions` and `operators` sub-directories with
the `*.svg` files used to describe the syntax of each function or operator.
These are all generated by the same tests that generate the functions and operators docs above.

### kibana

The `kibana` directory contains `definition` and `docs` sub-directories that are generated:

* `kibana/definition` - function definitions for kibana's ESQL editor
* `kibana/docs` - the inline docs for kibana

These are also generated as part of the unit tests described above.