diff --git a/internal/docs/readme.go b/internal/docs/readme.go index 256b7d2d9e..bf3036d6ef 100644 --- a/internal/docs/readme.go +++ b/internal/docs/readme.go @@ -27,6 +27,11 @@ type ReadmeFile struct { Error error } +const ( + doNotModifyStr string = ` +` +) + // AreReadmesUpToDate function checks if all the .md readme files are up-to-date. func AreReadmesUpToDate() ([]ReadmeFile, error) { packageRoot, err := packages.MustFindPackageRoot() @@ -204,6 +209,9 @@ func renderReadme(fileName, packageRoot, templatePath string, linksMap linkMap) } return linksMap.RenderLink(args[0], options) }, + "header": func(args ...string) (string, error) { + return doNotModifyStr, nil + }, }).ParseFiles(templatePath) if err != nil { return nil, fmt.Errorf("parsing README template failed (path: %s): %w", templatePath, err) diff --git a/internal/packages/archetype/_static/package-docs-readme.md.tmpl b/internal/packages/archetype/_static/package-docs-readme.md.tmpl index 003c89f703..25970dde12 100644 --- a/internal/packages/archetype/_static/package-docs-readme.md.tmpl +++ b/internal/packages/archetype/_static/package-docs-readme.md.tmpl @@ -1,84 +1,92 @@ - - + - +{{ `{{header}}` }} +# {{.Manifest.Title}} for Elastic -Use the {{.Manifest.Title}} integration to {purpose}. Then visualize that data in Kibana, create alerts to notify you if something goes wrong, and reference {data stream type} when troubleshooting an issue. +## Overview -For example, if you wanted to {sample use case} you could {action}. Then you can {visualize|alert|troubleshoot} by {action}. --> + +The {{.Manifest.Title}} for Elastic integration enables collection of ... +This integration facilitates ... -## Data streams +### Compatibility - + +This integration is compatible with ... - - +### How it works - - + - +## What data does this integration collect? -## Requirements + +The {{.Manifest.Title}} integration collects log messages of the following types: +* ... -You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it. -You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your own hardware. +### Supported use cases - + + +## What do I need to use this integration? -## Setup +Elastic Agent must be installed. For more details, check the Elastic Agent [installation instructions](docs-content://reference/fleet/install-elastic-agents.md). You can install only one Elastic Agent per host. - +Elastic Agent is required to stream data from the syslog or log file receiver and ship the data to Elastic, where the events will then be processed via the integration's ingest pipelines. -For step-by-step instructions on how to set up an integration, see the -[Getting started](https://www.elastic.co/guide/en/welcome-to-elastic/current/getting-started-observability.html) guide. + - +## How do I deploy this integration? - - +### Onboard / configure + + - - + - - -An example event for `{data stream name}` looks as following: +## Scaling -{code block with example} --> +For more information on architectures that can be used for scaling this integration, check the [Ingest Architectures](https://www.elastic.co/docs/manage-data/ingest/ingest-reference-architectures) documentation. - -{insert table} --> +## Reference - - +### ECS field Reference - - +### Sample Event - - + +These inputs can be used with this integration: +* ... - + +These APIs are used with this integration: +* ... diff --git a/internal/packages/archetype/_static/package-sample-event.json.tmpl b/internal/packages/archetype/_static/package-sample-event.json.tmpl new file mode 100644 index 0000000000..71b53c2c32 --- /dev/null +++ b/internal/packages/archetype/_static/package-sample-event.json.tmpl @@ -0,0 +1,3 @@ +{ + "description": "This is an example sample-event for {{.Manifest.Title}}. Replace it with a real sample event. Hint: If system tests exist, running `elastic-package test system --generate` will generate this file." +} diff --git a/internal/packages/archetype/package.go b/internal/packages/archetype/package.go index 19da014fd0..856b955d05 100644 --- a/internal/packages/archetype/package.go +++ b/internal/packages/archetype/package.go @@ -54,6 +54,14 @@ func createPackageInDir(packageDescriptor PackageDescriptor, cwd string) error { return fmt.Errorf("can't render package README: %w", err) } + if packageDescriptor.Manifest.Type == "integration" { + logger.Debugf("Write docs readme to _dev") + err = renderResourceFile(packageDocsReadme, &packageDescriptor, filepath.Join(baseDir, "_dev", "build", "docs", "README.md")) + if err != nil { + return fmt.Errorf("can't render package README in _dev: %w", err) + } + } + if license := packageDescriptor.Manifest.Source.License; license != "" { logger.Debugf("Write license file") err = licenses.WriteTextToFile(license, filepath.Join(baseDir, "LICENSE.txt")) @@ -78,6 +86,14 @@ func createPackageInDir(packageDescriptor PackageDescriptor, cwd string) error { return fmt.Errorf("can't render sample screenshot: %w", err) } + if packageDescriptor.Manifest.Type == "integration" { + logger.Debugf("Write sample sample_event") + err = renderResourceFile(packageSampleEvent, &packageDescriptor, filepath.Join(baseDir, "sample_event.json")) + if err != nil { + return fmt.Errorf("can't render sample sample_event: %w", err) + } + } + if packageDescriptor.Manifest.Type == "input" { logger.Debugf("Write base fields") err = renderResourceFile(fieldsBaseTemplate, &packageDescriptor, filepath.Join(baseDir, "fields", "base-fields.yml")) diff --git a/internal/packages/archetype/resources.go b/internal/packages/archetype/resources.go index 661d994f83..de3ef2b3cf 100644 --- a/internal/packages/archetype/resources.go +++ b/internal/packages/archetype/resources.go @@ -33,6 +33,9 @@ var packageImgSampleIcon []byte //go:embed _static/sampleScreenshot.png.b64 var packageImgSampleScreenshot string +//go:embed _static/package-sample-event.json.tmpl +var packageSampleEvent string + // Input Package templates //go:embed _static/input-package-agent-config.yml.tmpl