[ES|QL] Automate part of doc generation via annotations

[dej611]

Description

After #103686 I think part of the doc could be automated via scripting, at least for the following fields:

• signature
• parameters (and their description)
• description
• examples?

[elasticsearchmachine]

Pinging @elastic/es-analytics-geo (Team:Analytics)

[nik9000]

We already automate the parameter types and the railroad diagrams. But we could probably generate even more of this stuff. I'm not sure we'd want to generate all of, but a lot more.

[dej611]

I do not think generate all of it makes sense, but at least the structured part as described in the issue content. We already do that in Kibana and want to leverage the new SHOW FUNCTIONS to use ES as source of truth for it.

[nik9000]

Right now we generate two files and manually make another "main" file with the description and the name and description and an example. But I'll bet we could generate that "main" file and have it include hand written asciidoc files. That'd be pretty simple.

[nik9000]

I've automated the generation of the signature, examples, and parameters. And a file that links them all together. Basically all of this. A human being has to manually merge the data in the docs and annotations and replace the hand maintained docs with the generated ones. I'm going to make a list to track them.

[nik9000]

• Math
  • [x] abs
  • [x] acos
  • [x] asin
  • [x] atan
  • [x] atan2
  • [x] ceil
  • [x] cos
  • [x] cosh
  • [x] e #107331
  • [x] floor #107331
  • [x] log #106963
  • [x] log10 #106963
  • [x] pi #107331
  • [x] pow #107331
  • [x] round #107331
  • [x] sin
  • [x] sinh
  • [x] sqrt #107541
  • [x] tan
  • [x] tanh
  • [x] tau #107541
• String all in #107541, except left
  • [x] concat
  • [x] left
  • [x] length
  • [x] ltrim
  • [x] replace
  • [x] right
  • [x] rtrim
  • [x] split
  • [x] substring
  • [x] to_lower
  • [x] to_upper
  • [x] trim
• Date/time
  • [x] auto_bucket #107541
  • [x] date_diff #107541
  • [x] date_extract #107541
  • [x] date_format #107541
  • [x] date_parse #107541
  • [x] date_trunc
  • [x] now
• Spatial #107722
  • [x] st_intersects
  • [x] st_disjoint
  • [x] st_contains
  • [x] st_within
  • [x] st_x
  • [x] st_y
• Conversion all in #107541
  • [x] to_boolean
  • [x] to_cartesianpoint
  • [x] to_cartesianshape
  • [x] to_datetime
  • [x] to_degrees
  • [x] to_double
  • [x] to_geopoint
  • [x] to_geoshape
  • [x] to_integer
  • [x] to_ip
  • [x] to_long
  • [x] to_radians
  • [x] to_string
  • [x] to_unsigned_long
  • [x] to_version
• Conditional #107722
  • [x] case
  • [x] coalesce
  • [x] greatest
  • [x] least
• Multivalue Functions #107839
  • [x] mv_avg
  • [x] mv_concat
  • [x] mv_count
  • [x] mv_dedupe
  • [x] mv_first
  • [x] mv_last
  • [x] mv_max
  • [x] mv_median
  • [x] mv_min
  • [x] mv_sort
  • [x] mv_slice
  • [x] mv_sum
  • [x] mv_zip
• Operators (aren't generating code yet, but can be fixed) #108220, the parameter types of the items below are all generated automatically, for those not checked, it is because they are not defined in EsqlFunctionRegistry, we need a different way to generate signature, parameter descriptions and examples, it will be in a different PR.
  • [ ] binary
  • [ ] unary
  • [ ] logical
  • [ ] predicates
  • [x] cidr_match
  • [x] ends_with
  • [ ] in
  • [ ] like
  • [ ] rlike
  • [x] starts_with

[elasticsearchmachine]

Pinging @elastic/es-analytical-engine (Team:Analytics)