docs: update style guidelines (#2172)
Update the style guidelines. Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>pull/2213/head^2
parent
5ed0636f77
commit
2bb7b2efec
|
@ -41,4 +41,61 @@ This includes but is not limited to the following file types:
|
||||||
- YAML (*.yml, *.yaml)
|
- YAML (*.yml, *.yaml)
|
||||||
- Markdown (*.md)
|
- Markdown (*.md)
|
||||||
- JavaScript (*.js)
|
- JavaScript (*.js)
|
||||||
- TypeScript (*.ts, *.tsx)
|
- TypeScript (*.ts, *.tsx)
|
||||||
|
|
||||||
|
### Error Strings
|
||||||
|
|
||||||
|
Error messages should follow the standard go format. This format can be found in the [golang code review comments](https://github.com/golang/go/wiki/CodeReviewComments#error-strings)
|
||||||
|
however the key points are:
|
||||||
|
|
||||||
|
- errors should not start with capital letters (excluding proper nouns, acronyms, or initialism)
|
||||||
|
- errors should not end with punctuation
|
||||||
|
- these restrictions do not apply to logging, only the error type itself
|
||||||
|
|
||||||
|
### Configuration Documentation
|
||||||
|
|
||||||
|
The configuration documentation has a consistent format this section describes it as best as possible. It's recommended
|
||||||
|
to check additional sections for examples.
|
||||||
|
|
||||||
|
#### Layout
|
||||||
|
|
||||||
|
The first thing in the configuration documentation should be a description of the area. This is promptly followed by the
|
||||||
|
configuration heading (h2 / indent 2) which has an example full configuration.
|
||||||
|
|
||||||
|
Under the configuration example each option in the configuration needs to be documented with its own heading
|
||||||
|
(h3 / indent 3). Immediately following the heading is a div with some stylized icons.
|
||||||
|
|
||||||
|
The body of the section is to contain paragraphs describing the usage and information specific to that value.
|
||||||
|
|
||||||
|
|
||||||
|
**Example Stylized Icons:**
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div markdown="1">
|
||||||
|
type: string
|
||||||
|
{: .label .label-config .label-purple }
|
||||||
|
default: example
|
||||||
|
{: .label .label-config .label-blue }
|
||||||
|
required: no
|
||||||
|
{: .label .label-config .label-green }
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
##### type
|
||||||
|
|
||||||
|
This section has the type of the value in a semi human readable format. Some example values are `string`, `integer`,
|
||||||
|
`boolean`, `list(string)`, `duration`. This is immediately followed by the styles `.label`, `.label-config`,
|
||||||
|
`.label-purple`.
|
||||||
|
|
||||||
|
##### default
|
||||||
|
|
||||||
|
This section has the default of the value if one exists, this section can be completely omitted if there is no default.
|
||||||
|
This is immediately followed by the styles `.label`, `.label-config`,
|
||||||
|
`.label-blue`.
|
||||||
|
|
||||||
|
##### required
|
||||||
|
|
||||||
|
This section has the required status of the value and must be one of `yes`, `no`, or `situational`. Situational means it
|
||||||
|
depends on other configuration options. If it's situational the situational usage should be documented. This is
|
||||||
|
immediately followed by the styles `.label`, `.label-config`, and a traffic lights color label, i.e. if yes `.label-red`,
|
||||||
|
if no `.label-green`, or if situational `.label-yellow`.
|
||||||
|
|
Loading…
Reference in New Issue