docs: update style guidelines (#2172)

Update the style guidelines.

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>
pull/2213/head^2
James Elliott 2021-07-30 14:17:44 +10:00 committed by GitHub
parent 5ed0636f77
commit 2bb7b2efec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 58 additions and 1 deletions

View File

@ -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`.