[ES|QL] Automate part of doc generation via annotations #104247
Comments
dej611
added
>enhancement
Team:Docs
elasticsearchmachine
added
Team:Analytics
|
Pinging @elastic/es-analytics-geo (Team:Analytics) |
|
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. |
|
I do not think generate all of it makes sense, but at least the structured part as described in the issue content. |
|
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. |
This modifies the ESQL test infrastructure to generate more of the documentation for functions. It generates the *Description* section, the *Examples* section, and the *Parameters* section as separate files so we can use them as needed. It also generates a `layout` file that's just a guess as to how to render the whole thing. In some cases it'll work and we can use that instead of hand maintaining a "top level" description file for the function. Most newly generated files are unused. We have to chose to pick them up by replacing the sections we were manually maintaining with an include of the generated section. Or by replacing the entire hand maintained file with the generated top level file. Relates to elastic#104247
This modifies the ESQL test infrastructure to generate more of the documentation for functions. It generates the *Description* section, the *Examples* section, and the *Parameters* section as separate files so we can use them as needed. It also generates a `layout` file that's just a guess as to how to render the whole thing. In some cases it'll work and we can use that instead of hand maintaining a "top level" description file for the function. Most newly generated files are unused. We have to chose to pick them up by replacing the sections we were manually maintaining with an include of the generated section. Or by replacing the entire hand maintained file with the generated top level file. Relates to #104247
|
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. |
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.
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.
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 #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.
|
Pinging @elastic/es-analytical-engine (Team:Analytics) |
Description
After #103686 I think part of the doc could be automated via scripting, at least for the following fields:
The text was updated successfully, but these errors were encountered: