Docs: move source commands into a file per command (ESQL-1191)

I think it's a bit easier to deal with the files this way. They also
make a page per command so it lines up with the files which is nice.

Also I moved some of the examples into the docs. They were mostly there
already, but I linked them.

---------

Co-authored-by: Abdon Pijpelink <abdon.pijpelink@elastic.co>

docs/reference/esql/esql-source-commands.asciidoc

@@ -5,9 +5,9 @@
 <titleabbrev>Source commands</titleabbrev>
 ++++
 :keywords: {es}, ESQL, {es} query language, source commands
-:description: An ESQL source command produces a table, typically with data from {es}. 
+:description: An ESQL source command produces a table, typically with data from {es}.
 
-An ESQL source command produces a table, typically with data from {es}. 
+An ESQL source command produces a table, typically with data from {es}.
 
 image::images/esql/source-command.svg[A source command producing a table from {es},align="center"]
 
@@ -17,67 +17,6 @@ ESQL supports these source commands:
 * <<esql-row>>
 * <<esql-show>>
 
-[[esql-from]]
-=== `FROM`
-
-The `FROM` source command returns a table with up to 10,000 documents from a
-data stream, index, or alias. Each row in the resulting table represents a
-document. Each column corresponds to a field, and can be accessed by the name
-of that field.
-
-[source,esql]
-----
-FROM employees
-----
-
-You can use <<api-date-math-index-names,date math>> to refer to indices, aliases
-and data streams. This can be useful for time series data, for example to access
-today's index:
-
-[source,esql]
-----
-FROM <logs-{now/d}>
-----
-
-Use comma-separated lists or wildcards to query multiple data streams, indices,
-or aliases:
-
-[source,esql]
-----
-FROM employees-00001,employees-*
-----
-
-[[esql-row]]
-=== `ROW`
-
-The `ROW` source command produces a row with one or more columns with values
-that you specify. This can be useful for testing.
-
-[source,esql]
-----
-ROW a = 1, b = "two", c = null
-----
-
-Use angle brackets to create multi-value columns:
-
-[source,esql]
-----
-ROW a = [2, 1]
-----
-
-`ROW` supports the use of <<esql-functions,functions>>:
-
-[source,esql]
-----
-ROW a = ROUND(1.23, 0)
-----
-
-[[esql-show]]
-=== `SHOW <item>`
-
-The `SHOW <item>` source command returns information about the deployment and
-its capabilities:
-
-* Use `SHOW INFO` to return the deployment's version, build date and hash.
-* Use `SHOW FUNCTIONS` to return a list of all supported functions and a 
-synopsis of each function.
+include::source-commands/from.asciidoc[]
+include::source-commands/row.asciidoc[]
+include::source-commands/show.asciidoc[]

docs/reference/esql/source-commands/from.asciidoc

@@ -0,0 +1,29 @@
+[[esql-from]]
+=== `FROM`
+
+The `FROM` source command returns a table with up to 10,000 documents from a
+data stream, index, or alias. Each row in the resulting table represents a
+document. Each column corresponds to a field, and can be accessed by the name
+of that field.
+
+[source,esql]
+----
+FROM employees
+----
+
+You can use <<api-date-math-index-names,date math>> to refer to indices, aliases
+and data streams. This can be useful for time series data, for example to access
+today's index:
+
+[source,esql]
+----
+FROM <logs-{now/d}>
+----
+
+Use comma-separated lists or wildcards to query multiple data streams, indices,
+or aliases:
+
+[source,esql]
+----
+FROM employees-00001,employees-*
+----

docs/reference/esql/source-commands/row.asciidoc

@@ -0,0 +1,31 @@
+[[esql-row]]
+=== `ROW`
+
+The `ROW` source command produces a row with one or more columns with values
+that you specify. This can be useful for testing.
+
+[source,esql]
+----
+include::{esql-specs}/row.csv-spec[tag=example]
+----
+
+Which looks like:
+
+[%header,format=dsv,separator=|]
+|===
+include::{esql-specs}/row.csv-spec[tag=example-result]
+|===
+
+Use square brackets to create multi-value columns:
+
+[source,esql]
+----
+include::{esql-specs}/row.csv-spec[tag=multivalue]
+----
+
+`ROW` supports the use of <<esql-functions,functions>>:
+
+[source,esql]
+----
+include::{esql-specs}/row.csv-spec[tag=function]
+----

docs/reference/esql/source-commands/show.asciidoc

@@ -0,0 +1,9 @@
+[[esql-show]]
+=== `SHOW <item>`
+
+The `SHOW <item>` source command returns information about the deployment and
+its capabilities:
+
+* Use `SHOW INFO` to return the deployment's version, build date and hash.
+* Use `SHOW FUNCTIONS` to return a list of all supported functions and a
+synopsis of each function.

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

@@ -6,10 +6,15 @@ a:integer
 ;
 
 multipleFields
-row a = 1, b = 10, c = 100;
+// tag::example[]
+ROW a = 1, b = "two", c = null
+// end::example[]
+;
 
-a:integer | b:integer  | c:integer
-1 | 10 | 100
+// tag::example-result[]
+a:integer | b:keyword  | c:null
+1         | "two"      | null
+// end::example-result[]
 ;
 
 implicitNames
@@ -19,11 +24,28 @@ row 100, 10, c = 1;
 100 | 10 | 1
 ;
 
+multivalue
+// tag::multivalue[]
+ROW a = [2, 1]
+// end::multivalue[]
+;
+
+// tag::multivalue-result[]
+a:integer
+[2, 1]
+// end::multivalue-result[]
+;
+
 fieldFromFunctionEvaluation
-row a = round(1.23, 0);
+// tag::function[]
+ROW a = ROUND(1.23, 0)
+// end::function[]
+;
 
+// tag::function-result[]
 a:double
 1.0
+// end::function-result[]
 ;
 
 evalRow