[8.x] [ES|QL] Adds tech preview label in the docs (#199730) (#200118)

# Backport This will backport the following commits from `main` to `8.x`: - [[ES|QL] Adds tech preview label in the docs (#199730)](#199730)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Stratoula Kalafateli <efstratia.kalafateli@elastic.co>
elastic · Nov 14, 2024 · 58c23ab · 58c23ab
1 parent d1973ed
commit 58c23ab
Show file tree

Hide file tree

Showing 5 changed files with 158 additions and 9 deletions.
diff --git a/packages/kbn-language-documentation/scripts/generate_esql_docs.ts b/packages/kbn-language-documentation/scripts/generate_esql_docs.ts
@@ -13,6 +13,11 @@ import fs from 'fs';
 import path from 'path';
 import { functions } from '../src/sections/generated/scalar_functions';
 
+interface DocsSectionContent {
+  description: string;
+  preview?: boolean;
+}
+
 (function () {
   const pathToElasticsearch = process.argv[2];
   const { scalarFunctions, aggregationFunctions } = loadFunctionDocs(pathToElasticsearch);
@@ -41,8 +46,8 @@ function loadFunctionDocs(pathToElasticsearch: string) {
     .readdirSync(definitionsPath)
     .map((file) => JSON.parse(fs.readFileSync(`${definitionsPath}/${file}`, 'utf-8')));
 
-  const scalarFunctions = new Map<string, string>();
-  const aggregationFunctions = new Map<string, string>();
+  const scalarFunctions = new Map<string, DocsSectionContent>();
+  const aggregationFunctions = new Map<string, DocsSectionContent>();
 
   // Iterate over each file in the directory
   for (const file of docsFiles) {
@@ -64,21 +69,27 @@ function loadFunctionDocs(pathToElasticsearch: string) {
 
       // Add the function name and content to the map
       if (functionDefinition.type === 'eval') {
-        scalarFunctions.set(functionName, content);
+        scalarFunctions.set(functionName, {
+          description: content,
+          preview: functionDefinition.preview,
+        });
       }
       if (functionDefinition.type === 'agg') {
-        aggregationFunctions.set(functionName, content);
+        aggregationFunctions.set(functionName, {
+          description: content,
+          preview: functionDefinition.preview,
+        });
       }
     }
   }
 
   return { scalarFunctions, aggregationFunctions };
 }
 
-function writeFunctionDocs(functionDocs: Map<string, string>, pathToDocsFile: string) {
+function writeFunctionDocs(functionDocs: Map<string, DocsSectionContent>, pathToDocsFile: string) {
   const codeStrings = Array.from(functionDocs.entries()).map(([name, doc]) => {
     const docWithoutLinks = removeAsciiDocInternalCrossReferences(
-      doc,
+      doc.description,
       Array.from(functionDocs.keys())
     );
     return `
@@ -91,6 +102,7 @@ function writeFunctionDocs(functionDocs: Map<string, string>, pathToDocsFile: st
         defaultMessage: '${name.toUpperCase()}',
       }
     ),
+    preview: ${doc.preview || false},
     description: (
       <Markdown
         openLinksInNewTab

diff --git a/packages/kbn-language-documentation/src/components/shared/documentation.scss b/packages/kbn-language-documentation/src/components/shared/documentation.scss
@@ -71,6 +71,10 @@
   margin-top: $euiSizeXXL;
 }
 
+.documentation__techPreviewBadge {
+  margin-bottom: $euiSizeS;
+}
+
 .documentation__docsTextGroup {
   border-top: $euiBorderThin;
   padding-top: $euiSizeXXL;

diff --git a/packages/kbn-language-documentation/src/components/shared/documentation_content.tsx b/packages/kbn-language-documentation/src/components/shared/documentation_content.tsx
@@ -7,7 +7,8 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 import React from 'react';
-import { EuiFlexGroup, EuiText } from '@elastic/eui';
+import { i18n } from '@kbn/i18n';
+import { EuiFlexGroup, EuiText, EuiBetaBadge } from '@elastic/eui';
 import type { LanguageDocumentationSections } from '../../types';
 
 import './documentation.scss';
@@ -18,7 +19,7 @@ interface DocumentationContentProps {
   filteredGroups?: Array<{
     label: string;
     description?: string;
-    options: Array<{ label: string; description?: JSX.Element | undefined }>;
+    options: Array<{ label: string; description?: JSX.Element | undefined; preview?: boolean }>;
   }>;
   sections?: LanguageDocumentationSections;
 }
@@ -76,6 +77,23 @@ function DocumentationContent({
                         }
                       }}
                     >
+                      {helpItem.preview && (
+                        <EuiBetaBadge
+                          className="documentation__techPreviewBadge"
+                          label={i18n.translate('languageDocumentation.technicalPreviewLabel', {
+                            defaultMessage: 'Technical Preview',
+                          })}
+                          size="s"
+                          color="subdued"
+                          tooltipContent={i18n.translate(
+                            'languageDocumentation.technicalPreviewTooltip',
+                            {
+                              defaultMessage:
+                                'This functionality is experimental and not supported. It may change or be removed at any time.',
+                            }
+                          )}
+                        />
+                      )}
                       {helpItem.description}
                     </article>
                   );

diff --git a/packages/kbn-language-documentation/src/sections/generated/aggregation_functions.tsx b/packages/kbn-language-documentation/src/sections/generated/aggregation_functions.tsx
@@ -29,6 +29,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.avg', {
         defaultMessage: 'AVG',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -59,6 +60,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.count', {
         defaultMessage: 'COUNT',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -92,6 +94,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.count_distinct', {
         defaultMessage: 'COUNT_DISTINCT',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -125,6 +128,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.max', {
         defaultMessage: 'MAX',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -155,6 +159,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.median', {
         defaultMessage: 'MEDIAN',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -189,6 +194,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.median_absolute_deviation', {
         defaultMessage: 'MEDIAN_ABSOLUTE_DEVIATION',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -225,6 +231,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.min', {
         defaultMessage: 'MIN',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -255,6 +262,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.percentile', {
         defaultMessage: 'PERCENTILE',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -290,6 +298,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.st_centroid_agg', {
         defaultMessage: 'ST_CENTROID_AGG',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -323,6 +332,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.sum', {
         defaultMessage: 'SUM',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -353,6 +363,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.top', {
         defaultMessage: 'TOP',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab
@@ -383,6 +394,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.values', {
         defaultMessage: 'VALUES',
       }),
+      preview: true,
       description: (
         <Markdown
           openLinksInNewTab
@@ -418,6 +430,7 @@ export const functions = {
       label: i18n.translate('languageDocumentation.documentationESQL.weighted_avg', {
         defaultMessage: 'WEIGHTED_AVG',
       }),
+      preview: false,
       description: (
         <Markdown
           openLinksInNewTab