Writing README for modules
Guide for writing a good README file for modules.
Here at weeve we do not have specified requirements for a module's README file yet, but there is a couple of things worth mentioning in your documentation. In this tutorial we are going to describe them.
If you are not familiar with Markdown and writing README files, then we recommend this free online tutorial: Markdown Tutorial
Since your modules might be used by other developers from your company or externals (if you decide to make your modules public), then it is important to communicate to them some information that will be useful in the context of weeve ecosystem. Although we do not have strict company policy on README files, we recognize the following information to be helpful.
Currently weeve supports Docker, so all modules should be published to DockerHub. Hence, it is important to share a link to your image repository in DockerHub in the module's README file.
It should be mentioned whether your module is Input, Processing or Output. This information is helpful when connecting your module with other modules.
Another crucial element is a list of environment variables. Of course, you do not need to share values that you assigned to the environment variables of your module, but it would be useful to share variable names. These might be further used by developers when testing your module with their modules, as they could set some values to work on.
We recommend creating an environment variables table as the example bellow (this is from README of weeve Comparison Filter module):
Name | Environment Variables | Type | Description |
|---|---|---|---|
Input Label | INPUT_LABEL | string | The input label on which anomaly is detected. |
Condition | CONDITION | string | Condition for filtering data |
Compare Value | COMPARE_VALUE | string | The value to compare with |
List of dependencies is a list of libraries and packages that your container downloads in order to run your code. Although it cannot be modified by anyone pulling your module image from a repository, it is still useful to share this information.
bottle==0.12.21
requests==2.27.1
It also gives you an idea that a module was written in Python.
This is one of the most important information that must be shared in your module's README file. It is information about a type and a format of input that your module expects (it is not necessary for input modules). Therefore, a developer will understand what data can be passed to your module without breaking it. A good idea would be giving a minimum requirements for your module input data and an example to "visualize" it.
Input to this module is JSON body single object or array of objects:
{
"<INPUT_LABEL>": <Input data>,
}
Example single object:
{
temperature: 15,
}
Example array of object:
[
{
temperature: 15,
},
{
temperature: 21,
},
{
temperature: 25,
},
]
Input to this module is:
- JSON body single object, example:
{
"temperature": 15,
}
- array of JSON body objects, example:
[
{
"temperature": 15,
},
{
"temperature": 17,
}
]
It is also the most important information along the Module Input. This should specify what is the format of data outputted by your module (it is not necessary for output modules).
Output of this module is JSON body, in example:
{
"temperature": 12
}
Images file, that will be sent via HTTP POST Method with Form data, and key as image.
This module does not produce any output except Slack notifications.
In your module's README file, you should include any other information that you might consider useful for other developers.
If your module allows to apply some mathematic functions to a data like weeve Aggregator module does, you could include a short description of these functions:
Supported functions:
- mean (mean value that arrived within the specified interval)
- max (maximum value)
- spread (maximum - minimum value)
- median (median value recorded within the interval)
- sum (sum of all received values)
- stddv (standard deviation of values)
- count (number of data that arrived within the interval)
- first (first recorded data)
- min (minimum value)
- last (last recorded data)
If your module creates a notification alert that is later sent to a communication channels like Slack, WhatsApp or Discord, you could consider mentioning what type of alerts a user can expect. For instance, the following is mentioned in weeve Slack Alert module README:
Type | Text |
|---|---|
warning | WARNING for MachineName! Temperature reading shows 41.19 Celsius (< 49.0 Celsius). |
alarming | ALARM from MachineName! Detected an alarming reading of Temperature: 100 Celsius (> 20 Celsius). |
caution | CAUTION for MachineName! Temperature is 100 Celsius (>= 20 Celsius). |
broken | BROKEN device MachineName! Detected Temperature reading is -1.1 Celsius (<= -1 Celsius). |
README files should contain all necessary information that could be useful for other developers using your modules. If you need more inspiration for README formats, you can check out weeve GitHub repo.
Last modified 10mo ago