Skip to content

Latest commit

 

History

History
143 lines (125 loc) · 5.33 KB

add_package_readme.md

File metadata and controls

143 lines (125 loc) · 5.33 KB
Raw

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 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 |  |  |
...
  • url <link_key>: this placeholder is replaced by the URL defined in the links_table.yml file.
    • Example of usage: 
      Check {{ url "foo" }}
    • Let's assume that there exists a file links_table.yml with these contents: 
      links:
  foo: http://url.com.test
  help: http://other.url.com/help
    • Rendered output: 
      Check http://url.com.test
    • Requirements:
      • It is needed to define a file with the links definitions. More information in this section
  • url <link_key> <link_text>: this placeholder is replaced by the URL defined in the links_table.yml file and it creates a markdown link as [link_text](url)
    • Example of usage: 
      Check {{ url "help" "help guide" }}
    • Let's assume that there exists a file links_table.yml with these contents: 
      links:
  foo: http://url.com.test
  help: http://other.url.com/help
    • Rendered output: 
      Check [help guide](http://other.url.com/help)
    • Requirements:
      • It is needed to define a file with the links definitions. More information in this section

Requirements

Links definitions file

In order to be able to use url placeholder, links must be defined in a file.

This file by default is located at the root of the repository with the name links_table.yml. It can be overwritten by setting the environment variable ELASTIC_PACKAGE_LINKS_FILE_PATH with the path to corresponding YAML file.

The format of this file must be:

links:
  <key_1>: <url_1>
  <key_2>: <url_2>
  <key_3>: <url_3>

As these links are rendered in building time (running elastic-package build command), there are some considerations that developers need to take into account:

  • packages will be built using always the links defined in the given file (e.g. links_table.yml).
  • any needed change in links requires that a new version of the package must be published to update the corresponding README file.