From 3f406164d474d063a663901eb6537008e08a56d9 Mon Sep 17 00:00:00 2001 From: Mario Rodriguez Molins Date: Mon, 22 Aug 2022 12:14:38 +0200 Subject: [PATCH] Add package readme howto guide --- README.md | 2 +- cmd/build.go | 2 +- docs/howto/add_package_readme.md | 83 ++++++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 2 deletions(-) create mode 100644 docs/howto/add_package_readme.md diff --git a/README.md b/README.md index 7cbce69f0e..1c938b7189 100644 --- a/README.md +++ b/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". diff --git a/cmd/build.go b/cmd/build.go index d10b38fa8b..c1684623cf 100644 --- a/cmd/build.go +++ b/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". diff --git a/docs/howto/add_package_readme.md b/docs/howto/add_package_readme.md new file mode 100644 index 0000000000..baa65b998c --- /dev/null +++ b/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 `: 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 `: 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 | | | + ... + ```