[ES|QL] Displays The Command License Availability In Our Inline Docs #230358

bartoval · 2025-08-04T06:56:48Z

Summary

This PR is part of #216791

Provide iDocs badges for commands with license.

Creates a script to generate a command documentation file.
Creates a new command template file that can be used as a starting point for defining new commands and generating their documentation.
Clean up the original doc file
Small refactoring to share utils and types

examples:

elasticmachine · 2025-08-04T06:56:53Z

Pinging @elastic/kibana-esql (Team:ESQL)

bartoval · 2025-08-04T08:02:43Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_docs.ts

 const n = recast.types.namedTypes;
 import fs from 'fs';
 import path from 'path';
 import { functions } from '../src/sections/generated/scalar_functions';


I noticed that this existing script updates an existing functions file. However, if a file in the generated folder is missing or becomes corrupted, the script crashes. We could improve this behavior with a small change —either in this PR, in a separate one, or leave it as is for now, if it is not a relevant case.

Yeah I had also noticed it, it is a case that is not happening in reality (unless you deliberately add a new file) so I don't think it is very important to fix

bartoval · 2025-08-04T10:58:23Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_command_docs.ts

+    labelKey: string;
+    descriptionKey: string;
+  } {
+    const labelKeySuffixMap: Record<string, string> = {


I'm not a big fan of these bindings, but the only alternative is to change the names of the translation keys in the translation json files (and probably remove this function)

Yeah I am not in favor of this either. Why are you doing this? Is this about converting stings like aaa_bbb to aaaBBB?? Why don't you use the camelCase of lodash?

If the keys are different now that we automated is better to update them with the automated ones rather than hardcode them in the script.

We need to handle cases where the label keys in the translation files don’t match the command names exactly. For example, a label key might be "languageDocumentation.documentationESQL.lookupJoin", but the corresponding commandName is simply lookup.

In most cases, the label keys and command names follow a predictable pattern and can be generated programmatically. However, there are exceptions like the one above, where a manual mapping is required to ensure accuracy.

As part of this, I’ll be updating the keys in the translation files to align with these mappings.

stratoula

This looks very nice already, I left some comments

stratoula · 2025-08-04T11:33:44Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_docs.ts

 const n = recast.types.namedTypes;
 import fs from 'fs';
 import path from 'path';
 import { functions } from '../src/sections/generated/scalar_functions';


Yeah I had also noticed it, it is a case that is not happening in reality (unless you deliberately add a new file) so I don't think it is very important to fix

stratoula · 2025-08-04T11:37:26Z

src/platform/packages/private/kbn-language-documentation/package.json

+    "make:docs": "./scripts/make_docs.sh",
    "postmake:docs": "yarn run lint:fix",
-    "lint:fix": "cd ../../../../.. && node ./scripts/eslint --fix ./src/platform/packages/private/kbn-language-documentation/src/sections/generated"
+    "lint:fix": "cd ../../../../.. && node ./scripts/eslint --fix ./src/platform/packages/private/kbn-language-documentation/src/sections/generated ./src/platform/packages/private/kbn-language-documentation/src/sections/esql_documentation_sections.tsx"


Why this change??

stratoula · 2025-08-04T11:40:44Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_command_docs.ts

+  'commands'
+);
+
+interface CommandData {


I have to admin that these interface having similar names is confusing me a bit. Can we give more descriptive named here?

maybe CommandTemplateData
these are the object parameters we use to build the final doc

yes this sounds better!

stratoula · 2025-08-04T11:42:13Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_command_docs.ts

+/**
+ * Generates a documentation for a specific group of commands.
+ */
+function generateCommandsDoc({


These 2 functions the same

🤔 I have a function called generateCommandsDoc and one called generateCommandDoc

Are these the two functions we are talking about? Eventually I can change the name as generateCommandItemDoc

yes these 2, almost same names so it would be cool if they can be more descriptive.. This generateCommandItemDoc sounds much better ++

stratoula · 2025-08-04T11:46:26Z

src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_command_docs.ts

+    labelKey: string;
+    descriptionKey: string;
+  } {
+    const labelKeySuffixMap: Record<string, string> = {


Yeah I am not in favor of this either. Why are you doing this? Is this about converting stings like aaa_bbb to aaaBBB?? Why don't you use the camelCase of lodash?

If the keys are different now that we automated is better to update them with the automated ones rather than hardcode them in the script.

stratoula

Awesome, LGTM! I didnt test it again, only code review

elasticmachine · 2025-08-04T15:39:00Z

💚 Build Succeeded

Buildkite Build
Commit: a17b583

Metrics [docs]

Module Count

Fewer modules leads to a faster build time

id	before	after	diff
`esql`	129	131	+2
`lens`	1412	1414	+2
`stackAlerts`	276	278	+2
`unifiedSearch`	434	436	+2
total			+8

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
`esql`	260.5KB	260.6KB	+91.0B
`unifiedSearch`	343.3KB	343.4KB	+91.0B
total			+182.0B

Unknown metric groups

ESLint disabled in files

id	before	after	diff
`@kbn/language-documentation`	0	1	+1

Total ESLint disabled count

id	before	after	diff
`@kbn/language-documentation`	1	2	+1

History

cc @bartoval

…lastic#230358) ## Summary This PR is part of elastic#216791 Provide iDocs badges for commands with license. - Creates a script to generate a command documentation file. - Creates a new command template file that can be used as a starting point for defining new commands and generating their documentation. - Clean up the original doc file - Small refactoring to share utils and types examples: <img width="442" height="453" alt="change_point" src="https://github.com/user-attachments/assets/9da2f0a6-d0b9-4f38-bc2a-3857c94cbe2c" /> --------- Co-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>

bartoval added 2 commits August 4, 2025 08:29

feat: add function license info to idoc

f260037

feat: add idoc command license badge

32eadb3

bartoval self-assigned this Aug 4, 2025

bartoval requested a review from a team as a code owner August 4, 2025 06:56

bartoval added release_note:skip Skip the PR/issue when compiling release notes backport:skip This PR does not require backporting Feature:ES|QL ES|QL related features in Kibana Team:ESQL ES|QL related features in Kibana t// v9.2.0 labels Aug 4, 2025

refactor: create command doc from template

102fec0

bartoval force-pushed the esql_add_idoc_command_license_badge branch from 6f3a1f2 to 102fec0 Compare August 4, 2025 07:57

bartoval mentioned this pull request Aug 4, 2025

[ES|QL] Check the license + tier and suggest based on it #216791

Closed

9 tasks

bartoval commented Aug 4, 2025

View reviewed changes

bartoval force-pushed the esql_add_idoc_command_license_badge branch 4 times, most recently from 1dfdd29 to 93dec68 Compare August 4, 2025 10:31

bartoval commented Aug 4, 2025

View reviewed changes

fix: add escape for variables

7603b4b

bartoval force-pushed the esql_add_idoc_command_license_badge branch from 93dec68 to 7603b4b Compare August 4, 2025 11:06

Merge branch 'main' into esql_add_idoc_command_license_badge

17c24d6

stratoula reviewed Aug 4, 2025

View reviewed changes

bartoval and others added 2 commits August 4, 2025 14:47

Merge branch 'elastic:main' into esql_add_idoc_command_license_badge

41e4d8f

refactor: resolve PR comments

a17b583

stratoula approved these changes Aug 4, 2025

View reviewed changes

bartoval merged commit 39301c9 into elastic:main Aug 4, 2025
12 checks passed

wildemat mentioned this pull request Aug 7, 2025

pr 230826 #231022

Closed

10 tasks

bartoval deleted the esql_add_idoc_command_license_badge branch November 6, 2025 21:04

[ES|QL] Displays The Command License Availability In Our Inline Docs #230358

[ES|QL] Displays The Command License Availability In Our Inline Docs #230358

Uh oh!

Conversation

bartoval commented Aug 4, 2025

Summary

Uh oh!

elasticmachine commented Aug 4, 2025

Uh oh!

bartoval Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartoval Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stratoula left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartoval Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stratoula left a comment

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Aug 4, 2025

💚 Build Succeeded

Metrics [docs]

Module Count

Async chunks

ESLint disabled in files

Total ESLint disabled count

History

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bartoval Aug 4, 2025 •

edited

Loading

bartoval Aug 4, 2025 •

edited

Loading

bartoval Aug 4, 2025 •

edited

Loading