From 93cda053fe45d8bdacd76b19943b078c63caaac3 Mon Sep 17 00:00:00 2001 From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Date: Tue, 10 Dec 2024 19:21:00 +1100 Subject: [PATCH] [8.x] [Automatic Import] Use datastream description in readme (#203236) (#203516) # Backport This will backport the following commits from `main` to `8.x`: - [[Automatic Import] Use datastream description in readme (#203236)](https://github.com/elastic/kibana/pull/203236) ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) Co-authored-by: Bharat Pasupula <123897612+bhapas@users.noreply.github.com> --- .../build_integration.test.ts | 39 +++++++++++-------- .../integration_builder/build_integration.ts | 2 +- .../integration_builder/readme_files.test.ts | 8 ++-- .../integration_builder/readme_files.ts | 32 +++++++++++---- .../server/templates/build_readme.md.njk | 8 ++-- .../server/templates/description_readme.njk | 7 +++- .../server/templates/package_readme.md.njk | 8 ++-- 7 files changed, 65 insertions(+), 39 deletions(-) diff --git a/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.test.ts b/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.test.ts index 7d2f3db91bdd0..aa772ac73f482 100644 --- a/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.test.ts +++ b/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.test.ts @@ -209,24 +209,29 @@ describe('buildPackage', () => { await buildPackage(testIntegration); - expect(createReadme).toHaveBeenCalledWith(integrationPath, testIntegration.name, [ - { - datastream: firstDatastreamName, - fields: [ - { name: 'name a', description: 'description 1', type: 'type 1' }, + expect(createReadme).toHaveBeenCalledWith( + integrationPath, + testIntegration.name, + testIntegration.dataStreams, + [ + { + datastream: firstDatastreamName, + fields: [ + { name: 'name a', description: 'description 1', type: 'type 1' }, - { name: 'name b', description: 'description 1', type: 'type 1' }, - ], - }, - { - datastream: secondDatastreamName, - fields: [ - { name: 'name c', description: 'description 2', type: 'type 2' }, - { name: 'name d', description: 'description 2', type: 'type 2' }, - { name: 'name e', description: 'description 3', type: 'type 3' }, - ], - }, - ]); + { name: 'name b', description: 'description 1', type: 'type 1' }, + ], + }, + { + datastream: secondDatastreamName, + fields: [ + { name: 'name c', description: 'description 2', type: 'type 2' }, + { name: 'name d', description: 'description 2', type: 'type 2' }, + { name: 'name e', description: 'description 3', type: 'type 3' }, + ], + }, + ] + ); }); }); diff --git a/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.ts b/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.ts index f374d468d1550..77ea45d2f006e 100644 --- a/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.ts +++ b/x-pack/plugins/integration_assistant/server/integration_builder/build_integration.ts @@ -59,7 +59,7 @@ export async function buildPackage(integration: Integration): Promise { }; }); - createReadme(packageDir, integration.name, fieldsPerDatastream); + createReadme(packageDir, integration.name, integration.dataStreams, fieldsPerDatastream); const zipBuffer = await createZipArchive(workingDir, packageDirectoryName); removeDirSync(workingDir); diff --git a/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.test.ts b/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.test.ts index ae9080fff8a74..2cb350458378e 100644 --- a/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.test.ts +++ b/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.test.ts @@ -59,7 +59,7 @@ describe('createReadme', () => { }, ]; - createReadme(integrationPath, testIntegration.name, fields); + createReadme(integrationPath, testIntegration.name, testIntegration.dataStreams, fields); expect(createSync).toHaveBeenCalledWith( `${integrationPath}/_dev/build/docs/README.md`, @@ -103,7 +103,7 @@ describe('createReadme', () => { }, ]; - createReadme(integrationPath, testIntegration.name, fields); + createReadme(integrationPath, testIntegration.name, testIntegration.dataStreams, fields); const firstDatastreamFieldsDisplayed = ` | Field | Description | Type | @@ -139,7 +139,7 @@ describe('createReadme', () => { }, ]; - createReadme(integrationPath, testIntegration.name, fields); + createReadme(integrationPath, testIntegration.name, testIntegration.dataStreams, fields); expect(createSync).toHaveBeenCalledWith( `${integrationPath}/_dev/build/docs/README.md`, @@ -165,7 +165,7 @@ describe('createReadme', () => { }, ]; - createReadme(integrationPath, testIntegration.name, fields); + createReadme(integrationPath, testIntegration.name, testIntegration.dataStreams, fields); const firstDatastreamFieldsDisplayed = ` | Field | Description | Type | diff --git a/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.ts b/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.ts index 16c62c73cc325..f8d35d2647879 100644 --- a/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.ts +++ b/x-pack/plugins/integration_assistant/server/integration_builder/readme_files.ts @@ -8,29 +8,46 @@ import { Environment, FileSystemLoader } from 'nunjucks'; import { join as joinPath } from 'path'; +import { DataStream } from '../../common'; import { createSync, ensureDirSync } from '../util'; -export function createReadme(packageDir: string, integrationName: string, fields: object[]) { - createPackageReadme(packageDir, integrationName, fields); - createBuildReadme(packageDir, integrationName, fields); +export function createReadme( + packageDir: string, + integrationName: string, + datastreams: DataStream[], + fields: object[] +) { + createPackageReadme(packageDir, integrationName, datastreams, fields); + createBuildReadme(packageDir, integrationName, datastreams, fields); } -function createPackageReadme(packageDir: string, integrationName: string, fields: object[]) { +function createPackageReadme( + packageDir: string, + integrationName: string, + datastreams: DataStream[], + fields: object[] +) { const dirPath = joinPath(packageDir, 'docs/'); // The readme nunjucks template files should be named in the format `somename_readme.md.njk` and not just `readme.md.njk` // since any file with `readme.*` pattern is skipped in build process in buildkite. - createReadmeFile(dirPath, 'package_readme.md.njk', integrationName, fields); + createReadmeFile(dirPath, 'package_readme.md.njk', integrationName, datastreams, fields); } -function createBuildReadme(packageDir: string, integrationName: string, fields: object[]) { +function createBuildReadme( + packageDir: string, + integrationName: string, + datastreams: DataStream[], + fields: object[] +) { const dirPath = joinPath(packageDir, '_dev/build/docs/'); - createReadmeFile(dirPath, 'build_readme.md.njk', integrationName, fields); + createReadmeFile(dirPath, 'build_readme.md.njk', integrationName, datastreams, fields); } function createReadmeFile( targetDir: string, templateName: string, integrationName: string, + datastreams: DataStream[], fields: object[] ) { ensureDirSync(targetDir); @@ -43,6 +60,7 @@ function createReadmeFile( const template = env.getTemplate(templateName); const renderedTemplate = template.render({ package_name: integrationName, + datastreams, fields, }); diff --git a/x-pack/plugins/integration_assistant/server/templates/build_readme.md.njk b/x-pack/plugins/integration_assistant/server/templates/build_readme.md.njk index 1b58e55aebd37..92b03575b10fb 100644 --- a/x-pack/plugins/integration_assistant/server/templates/build_readme.md.njk +++ b/x-pack/plugins/integration_assistant/server/templates/build_readme.md.njk @@ -1,8 +1,8 @@ {% include "./description_readme.njk" %} -{% for data_stream in fields %} -### {{ data_stream.datastream }} - -Insert a description of the datastream here. +{% for datastream in datastreams %} +### {{ datastream.title }} +{{ datastream.description }}{% endfor %} +{% for data_stream in fields %} {% raw %}{{fields {% endraw %}"{{ data_stream.datastream }}"{% raw %}}}{% endraw %} {% endfor %} \ No newline at end of file diff --git a/x-pack/plugins/integration_assistant/server/templates/description_readme.njk b/x-pack/plugins/integration_assistant/server/templates/description_readme.njk index 91c1bf6f1b40c..9fe32dccb2b2b 100644 --- a/x-pack/plugins/integration_assistant/server/templates/description_readme.njk +++ b/x-pack/plugins/integration_assistant/server/templates/description_readme.njk @@ -7,8 +7,11 @@ Check the [overview guidelines](https://www.elastic.co/guide/en/integrations-dev ## Datastreams -Provide a high-level overview of the kind of data that is collected by the integration. -Check the [datastreams guidelines](https://www.elastic.co/guide/en/integrations-developer/current/documentation-guidelines.html#idg-docs-guidelines-datastreams) for more information. +{% for datastream in datastreams %} +### {{ datastream.title }} + +{{ datastream.description }} +{% endfor %} ## Requirements diff --git a/x-pack/plugins/integration_assistant/server/templates/package_readme.md.njk b/x-pack/plugins/integration_assistant/server/templates/package_readme.md.njk index bd56aba5ac1e5..3131822e3f2ee 100644 --- a/x-pack/plugins/integration_assistant/server/templates/package_readme.md.njk +++ b/x-pack/plugins/integration_assistant/server/templates/package_readme.md.njk @@ -1,15 +1,15 @@ {% include "./description_readme.njk" %} -{% for data_stream in fields %} -### {{ data_stream.datastream }} +{% for datastream in datastreams %} +### {{ datastream.title }} -Insert a description of the datastream here. +{{ datastream.description }}{% endfor %} **ECS Field Reference** Please refer to the following [document](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) for detailed information on ECS fields. **Exported fields** - +{% for data_stream in fields %} | Field | Description | Type | |---|---|---| {% for field in data_stream.fields %}| {{ field.name }} | {{ field.description | default('') | replace('\n', ' ') | trim }} | {{ field.type }} |