Add package readme howto guide

README.md

@@ -94,7 +94,7 @@ _Context: package_
 
 Use this command to build a package. Currently it supports only the "integration" package type.
 
-Built packages are stored in the "build/" folder located at the root folder of the local Git repository checkout that contains your package folder. The command will also render the README file in your package folder if there is a corresponding template file present in "_dev/build/docs/README.md". All "_dev" directories under your package will be omitted.
+Built packages are stored in the "build/" folder located at the root folder of the local Git repository checkout that contains your package folder. The command will also render the README file in your package folder if there is a corresponding template file present in "_dev/build/docs/README.md". All "_dev" directories under your package will be omitted. For details on how to generate and syntax of this README, see the [HOWTO guide](./docs/howto/add_package_readme.md).
 
 Built packages are served up by the Elastic Package Registry running locally (see "elastic-package stack"). If you want a local package to be served up by the local Elastic Package Registry, make sure to build that package first using "elastic-package build".
 

cmd/build.go

@@ -20,7 +20,7 @@ import (
 
 const buildLongDescription = `Use this command to build a package. Currently it supports only the "integration" package type.
 
-Built packages are stored in the "build/" folder located at the root folder of the local Git repository checkout that contains your package folder. The command will also render the README file in your package folder if there is a corresponding template file present in "_dev/build/docs/README.md". All "_dev" directories under your package will be omitted.
+Built packages are stored in the "build/" folder located at the root folder of the local Git repository checkout that contains your package folder. The command will also render the README file in your package folder if there is a corresponding template file present in "_dev/build/docs/README.md". All "_dev" directories under your package will be omitted. For details on how to generate and syntax of this README, see the [HOWTO guide](./docs/howto/add_package_readme.md).
 
 Built packages are served up by the Elastic Package Registry running locally (see "elastic-package stack"). If you want a local package to be served up by the local Elastic Package Registry, make sure to build that package first using "elastic-package build".
 

docs/howto/add_package_readme.md

@@ -0,0 +1,83 @@
+# HOWTO: Add a README.md in a package
+
+## Introduction
+
+Each package should have a README to explain all the details related to a given package at `docs/README.md` path.
+
+In order to help developers, this file is intended to be auto-generated by the `elastic-package build` command.
+The template used to generate the final README must be located at `_dev/build/docs/README.md`.
+This is the file that developers should be writting/updating.
+
+As a note, there could be more than one readme file present in `_dev/build/docs/*.md`.
+`elastic-package build` command will render and write all those files into `docs/` folder.
+
+# Markdown templates
+
+Files in `_dev/build/docs/*.md` follow Markdown syntax and they are rendered using [text/template](https://pkg.go.dev/text/template) package.
+In addition to Markdown syntax, there are some additional placeholders that can be used in order to help
+to complete the information shown to the user.
+
+## Placeholders
+
+List of placeholders that can be used in the Markdown templates:
+
+- `event <data_stream>`: this placeholder is replaced by the contents of the given sample event from the data stream set as parameter.
+    - Example of usage:
+      ```
+      {{ event "metrics" }}
+      ```
+    - This placeholder looks for the following path `data_stream/metrics/sample_event.json` in the package.
+      The contents of that file will be written in the `docs/README.md` where the placeholder is.
+    - Example of the rendered output:
+      ````
+      An example event for `metrics` looks as following:
+
+      ```json
+      {
+          "@timestamp": "2022-07-28T09:54:47.993Z",
+          "agent": {
+              "ephemeral_id": "fb0962b4-3f3f-48d6-81d6-3df63366f744",
+              "id": "97cba3e2-ea7d-4d80-aa69-75752faa1576",
+              "name": "docker-fleet-agent",
+              "type": "metricbeat",
+              "version": "8.0.0"
+          },
+          "data_stream": {
+              "dataset": "elastic_package_registry.metrics",
+              "namespace": "ep",
+              "type": "metrics"
+          },
+          "ecs": {
+              "version": "8.3.1"
+          },
+          "event": {...},
+          "host": {...},
+          "metricset": {
+              "name": "collector",
+              "period": 300000
+          },
+          "package_registry": {...},
+          "service": {...}
+       }
+       ```
+       ````
+- `fields <data_stream>`: this placeholder is replaced by the contents of the fields of the data stream set as parameter.
+    - Example of usage:
+      ```
+      {{ fields "metrics" }}
+      ```
+    - This placeholder looks for the following folder `data_stream/metrics/fields/` in the package.
+      This folder must contain all the field definitions for this package. `elastic-package build` command reads
+      all these files and writes into the final readme (`docs/README.md`) a table with all their information.
+    - Example of the rendered output:
+      ```
+      **Exported fields**
+
+      | Field | Description | Type | Unit | Metric Type |
+      |---|---|---|---|---|
+      | @timestamp | Event timestamp. | date |  |  |
+      | data_stream.dataset | Data stream dataset. | constant_keyword |  |  |
+      | data_stream.namespace | Data stream namespace. | constant_keyword |  |  |
+      | data_stream.type | Data stream type. | constant_keyword |  |  |
+      ...
+      ```