ESQL: Generate more docs #106367
ESQL: Generate more docs #106367
Conversation
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
|
Documentation preview: |
elasticsearchmachine
added
Team:Docs
|
Pinging @elastic/es-docs (Team:Docs) |
|
Pinging @elastic/es-analytical-engine (Team:Analytics) |
| renderParametersList(description.argNames(), description.argDescriptions()); | ||
| renderDescription(description.description()); | ||
| boolean hasExamples = renderExamples(EsqlFunctionRegistry.functionInfo(definition)); | ||
| renderFullLayout(name, hasExamples); | ||
| return; |
There was a problem hiding this comment.
I intentionally only plugged this into the functions because I wanted to be able to think about operators in a separate PR.
There was a problem hiding this comment.
But I wrote all the functions so we can use them for operators if we want. Just plug them in the same was as we do above.
|
My expectation is that this will change no or very few docs. Most of the generated files haven't been included in the docs build yet. We want to eyeball each one as we pull it in. |
|
There were a few accidental diffs. I'm working on it. Here's a diff of the generated docs: elastic/built-docs@master...elasticsearch_bk_106367 |
|
Ok. This change minimizes the docs changes - it's now just standardizing. |
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
layoutfile 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