[canvas] [docs] Canvas docs assume knowledge of the syntax/grammar of the expression language

[wylieconlon]

As I've been looking through the Canvas docs, I've been trying to contextualize the various functions and finding it difficult. Specifically, the Function Reference page is great for understanding what should be possible, but not for combining these into a useful whole.

My proposal is to:

• Include a few paragraphs or examples to define the Expression Grammar
• Show examples based on the default Canvas elements in use

So for example, the first paragraph right now is:

Behind the scenes, Canvas is driven by a powerful expression language, with dozens of functions and other capabilities, including table transforms, type casting, and sub-expressions.

I think this page should also document what a simple Canvas expression looks like:

filters
| essql 
  query="...."
| pointseries x="Var1" y="KEY1" color="LIC"
| plot defaultStyle={seriesStyle bars=0.75 horizontalBars=true} legend="se"
| render

It should use that simple expression to point out:

• It's evaluated top down
• There's a nested expression with {} syntax
• There aren't any multi fields, but there should be an example that supports it
• There are two types of expressions, functions and renderers

Along the same lines, each function explanation is very hard to understand as a non-expert. For example, this is the current documentation for math:

Interprets a TinyMath math expression using a number or datatable as context. The datatable columns are available by their column name. If the context is a number, it is available as value.

Argument | Type | Description
Unnamed * Alias: expression | string

So how do I actually use it?

[elasticmachine]

Pinging @elastic/kibana-docs (Team:Docs)

[elasticmachine]

Pinging @elastic/kibana-canvas (Team:Canvas)

[ryankeairns]

Thanks @wylieconlon ! The good news is that we have doc with a number of examples code blocks already in it. In my opinion, this is currently our most significant adoption blocker.

I'm closing my issue in favor of this one which has much more detail - #47455

[timductive]

Closed with merge of #51494