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)
|
||||
- Markdown (*.md)
|
||||
- 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