ESQL: Generate kibana inline docs #106782
Conversation
This takes a stab at generating the markdown files that Kibana uses for its inline help. It doesn't include all of the examples because the `@Example` annotation is not filled in - we're tracking that in elastic#104247 (comment) There are some links in the output and they are in markdown syntax. We should figure out how to make them work for kibana.
elasticsearchmachine
added
Team:Docs
|
Pinging @elastic/es-docs (Team:Docs) |
|
Pinging @elastic/es-analytical-engine (Team:Analytics) |
|
Wait. Silly test security exception. Fixing. |
Done. |
| builder.append(info.description()).append("\n\n"); | ||
|
|
||
| if (info.examples().length > 0) { | ||
| Example example = info.examples()[0]; |
There was a problem hiding this comment.
It would be nice to have all examples. But ok for the first one as first step.
There was a problem hiding this comment.
I'm happy to include all of them if you want. I just didn't see a place where you had more than one.
There was a problem hiding this comment.
This looks wrong to me.
auto_bucket has 4 arguments (field, buckets, from, to) while here there are 4 different signatures only with the field argument. 🤔
There was a problem hiding this comment.
I see the auto_bucket is not ticked in the related issue. Is that because of it?
There was a problem hiding this comment.
I'll bet it's a funny way we're testing it. Checking.
There was a problem hiding this comment.
Yeah. It's because we're testing this in a weird weird way. I should fix the way we test this.
Now, here's an interesting question - can I check these? If a function isn't variadic I can just assert that the sizes are the same.
|
The shape looks correct to me, probably this requires also @drewdaemon to have a look as he's now in charge of the es|ql project on the kibana side. |
From my side it'd be better to merge it but have y'all not use it. That way we can look at what it builds and say "this bit isn't ready". But I'll do whatever's easiest for you. |
|
As long as we receive a ping on when it's complete I guess it's ok for us. But let's check @drewdaemon 's preference. |
| "signatures" : [ | ||
| { | ||
| "params" : [ | ||
| { | ||
| "name" : "field", | ||
| "type" : "datetime", | ||
| "optional" : false, | ||
| "description" : "" | ||
| } | ||
| ], | ||
| "variadic" : false, | ||
| "returnType" : "datetime" | ||
| }, |
There was a problem hiding this comment.
Looking at the docs, this function has 4 parameters but I only see one here.
|
@luigidellaquila While working on this I found a bug in the way we decided whether or not to check if the annotations line up with the tested signatures - it'd only do it if there was more than one tested signature. So there were some cases where we weren't running it. That is my fault. I made the mistake a while back. Anyway! I reworked it. There's one test that was failing - CASE - it just has tests for Could you have a look at this PR? |
This improves the tests for AUTO_BUCKET marginally, specifically so that it tests all valid combinations of arguments and generates a correct types table. This'll combine nicely with elastic#106782 to generate the signatures that kibana needs for it's editor.
|
I'm going to merge main into this, rebuild everything, and then get this landed. We can start playing with it in Kibana from there. |
|
Thanks for all the feedback friends! We'll iterate on the fun around CASE and AUTO_BUCKET soon. And aggs. And operators. |
nik9000
added
the
auto-merge-without-approval
This moves the test cases declared in the tests for ESQL's LOCATE function to test cases which will cause elastic#106782 to properly generate all of the available signatures. It also buys us all of testing for incorrect parameter combinations.
This improves the tests for AUTO_BUCKET marginally, specifically so that it tests all valid combinations of arguments and generates a correct types table. This'll combine nicely with #106782 to generate the signatures that kibana needs for it's editor.
|
Grumble grumble ci |
This moves the test cases declared in the tests for ESQL's LOCATE function to test cases which will cause #106782 to properly generate all of the available signatures. It also buys us all of testing for incorrect parameter combinations.
|
@drewdaemon - it looks like the signature we generate for the ROUND function isn't correct - it's missing a lot of supported types. Working on it. |
This takes a stab at generating the markdown files that Kibana uses for its inline help. It doesn't include all of the examples because the
@Exampleannotation is not filled in - we're tracking that in #104247 (comment)There are some links in the output and they are in markdown syntax. We should figure out how to make them work for kibana.