Update new package README template

internal/docs/readme.go

@@ -27,6 +27,11 @@ type ReadmeFile struct {
 	Error    error
 }
 
+const (
+	doNotModifyStr string = `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->`
+)
+
 // AreReadmesUpToDate function checks if all the .md readme files are up-to-date.
 func AreReadmesUpToDate() ([]ReadmeFile, error) {
 	packageRoot, err := packages.MustFindPackageRoot()
@@ -214,7 +219,10 @@ func renderReadme(fileName, packageRoot, templatePath string, linksMap linkMap)
 	if err != nil {
 		return nil, fmt.Errorf("executing template failed: %w", err)
 	}
-	return rendered.Bytes(), nil
+
+	// Prepend the doNotModifyStr to all generated files
+	result := append([]byte(doNotModifyStr+"\n"), rendered.Bytes()...)
+	return result, nil
 }
 
 func readReadme(fileName, packageRoot string) ([]byte, bool, error) {

internal/docs/readme_test.go

@@ -30,7 +30,9 @@ func TestGenerateReadme(t *testing.T) {
 			readmeTemplateContents: `
 # README
 Introduction to the package`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package`,
 		},
@@ -83,7 +85,9 @@ func TestRenderReadmeWithLinks(t *testing.T) {
 Introduction to the package
 {{ url "foo" }}
 {{ url "foo" "Example" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 http://www.example.com/bar
@@ -127,7 +131,9 @@ func TestRenderReadmeWithSampleEvent(t *testing.T) {
 # README
 Introduction to the package
 {{ event "example" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 An example event for ` + "`example`" + ` looks as following:
@@ -184,7 +190,9 @@ func TesRenderReadmeWithFields(t *testing.T) {
 # README
 Introduction to the package
 {{ fields }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 **Exported fields**
@@ -207,7 +215,9 @@ Introduction to the package
 # README
 Introduction to the package
 {{ fields "example" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 **Exported fields**
@@ -230,7 +240,9 @@ Introduction to the package
 # README
 Introduction to the package
 {{ fields "notexist" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 **Exported fields**

internal/packages/archetype/_static/package-docs-readme.md.tmpl

@@ -1,84 +1,105 @@
-<!-- Use this template language as a starting point, replacing {placeholder text} with details about the integration. -->
-<!-- Find more detailed documentation guidelines in https://github.com/elastic/integrations/blob/main/docs/documentation_guidelines.md -->
+<!-- This template can be used as a starting point for writing documentation for your new integration. For each section, fill in the details
+described in the comments.
 
-# {{.Manifest.Title}}
+Find more detailed documentation guidelines in https://www.elastic.co/docs/extend/integrations/documentation-guidelines
+-->
 
-<!-- The {{.Manifest.Title}} integration allows you to monitor {name of service}. {name of service} is {describe service}.
+<!-- Do not remove header -->
+{{ `{{header}}` }}
+# {{.Manifest.Title}} Integration 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}. -->
+<!-- Complete this section with a short summary of what data this integration collects and what use cases it enables -->
+The {{.Manifest.Title}} integration for Elastic enables collection of ...
+This integration facilitates ...
 
-## Data streams
+### Compatibility
 
-<!-- The {{.Manifest.Title}} integration collects {one|two} type{s} of data streams: {logs and/or metrics}. -->
+<!-- Complete this section with information on what 3rd party software or hardware versions this integration is compatible with -->
+This integration is compatible with ...
 
-<!-- If applicable -->
-<!-- **Logs** help you keep a record of events happening in {service}.
-Log data streams collected by the {name} integration include {sample data stream(s)} and more. See more details in the [Logs](#logs-reference). -->
+### How it works
 
-<!-- If applicable -->
-<!-- **Metrics** give you insight into the state of {service}.
-Metric data streams collected by the {name} integration include {sample data stream(s)} and more. See more details in the [Metrics](#metrics-reference). -->
+<!-- Add a high level overview on how this integration works. For example, does it collect data from API calls or recieving data from a network or file.-->
 
-<!-- Optional: Any additional notes on data streams -->
+## What data does this integration collect?
 
-## Requirements
+<!-- Complete this section with information on what types of data the integration collects, and link to reference documentation if available -->
+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
 
-<!--
-	Optional: Other requirements including:
-	* System compatibility
-	* Supported versions of third-party products
-	* Permissions needed
-	* Anything else that could block a user from successfully using the integration
--->
+<!-- Add details on the use cases that can be enabled by using this integration. Explain why a user would want to install and use this integration. -->
 
-## Setup
+## What do I need to use this integration?
 
-<!-- Any prerequisite instructions -->
+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.
 
-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.
+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.
 
-<!-- Additional set up instructions -->
+<!-- List any other vendor-specific prerequisites needed before starting to install the integration. -->
 
-<!-- If applicable -->
-<!-- ## Logs reference -->
+## How do I deploy this integration?
 
-<!-- Repeat for each data stream of the current type -->
-<!-- ### {Data stream name}
+### Onboard / configure
 
-The `{data stream name}` data stream provides events from {source} of the following types: {list types}. -->
+<!-- List the steps that will need to be followed in order to completely set up a working inte completely set up a working integration.
+For integrations that support multiple input types, be sure to add steps for all inputs.
+-->
+
+### Validation
+
+<!-- How can the user test whether the integration is working? Including example commands or test files if applicable -->
+
+## Troubleshooting
 
-<!-- Optional -->
-<!-- #### Example
+For help with Elastic ingest tools, check [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems).
 
-An example event for `{data stream name}` looks as following:
+<!-- Add any vendor specific troubleshooting here.
 
-{code block with example} -->
+Are there common issues or “gotchas” for deploying this integration? If so, how can they be resolved?
+If applicable, links to the third-party software’s troubleshooting documentation.
+-->
+
+## Scaling
 
-<!-- #### Exported fields
+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} -->
+<!-- Add any vendor specific scaling information here -->
 
-<!-- If applicable -->
-<!-- ## Metrics reference -->
+## Reference
 
 <!-- Repeat for each data stream of the current type -->
 <!-- ### {Data stream name}
 
 The `{data stream name}` data stream provides events from {source} of the following types: {list types}. -->
 
-<!-- Optional -->
-<!-- #### Example
+### ECS field reference
+
+<!-- Repeat and fill in the comment block below for each data stream of the current type. {{ `{{fields}}` }} will be replaced by a generated list of all fields from the `fields/` directory of the data stream when building the integration. -->
+<!--
+#### {data stream name} fields
+{{ `{{fields {data_stream_name} }}` }}
+
+-->
+
+### Sample Event
+
+<!-- Repeat and fill in the comment block below for each data stream of the current type. {{ `{{event}}` }} will be replace by a sample event, taken from `sample_event.json`, when building this integration. -->
+<!--
+{{ `{{event {data_stream_name} }}` }}
+-->
 
-An example event for `{data stream name}` looks as following:
+### Inputs used
 
-{code block with example} -->
+<!-- List inputs used in this integration, and link to the documentation -->
+These inputs can be used with this integration:
+* ...
 
-<!-- #### Exported fields
+### API usage
 
-{insert table} -->
+<!-- For integrations that use APIs to collect data, document all the APIs that are used, and link to relevent information -->
+These APIs are used with this integration:
+* ...

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."
+}

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 != "content" {
+		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"))

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

test/packages/false_positives/cisco_asa/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Cisco ASA Integration
 
 This integration is for Cisco ASA network device's logs. It includes the following

test/packages/false_positives/docker_failing_test_service/docs/README.md

@@ -1 +1,3 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Test integration

test/packages/false_positives/httpjson_false_positive_asserts/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Custom API input integration
 
 The custom API input integration is used to ingest data from custom RESTful API's that do not currently have an existing integration.

test/packages/false_positives/long_integers_as_json_numbers/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Long Integer Tests
 
 An example event for `test` looks as following:

test/packages/false_positives/nginx_missing_deployer/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Nginx Integration
 
 This integration periodically fetches metrics from [Nginx](https://nginx.org/) servers. It can parse access and error

test/packages/false_positives/prometheus/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Prometheus Integration
 
 This integration can collect metrics from:

test/packages/other/ecs_mappings/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # ECS Mappings Test
 
 Test package to verify support for ECS mappings available to integrations running on stack version 8.13.0 and later.

test/packages/other/fields_tests/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Fields Tests
 
 An example event for `first` looks as following:

test/packages/other/imported_mappings_tests/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Imported Mappings Tests
 
 An example event for `first` looks as following:

test/packages/other/long_integers/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Long Integer Tests
 
 An example event for `test` looks as following:

test/packages/other/readme_links/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Readme Links
 
 Examples of links:

test/packages/other/with_links/docs/README.md

@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Imported Mappings Tests
 
 An example event for `first` looks as following: