Skip to content

Commit ba6e507

Browse files
dale3hfabaff
dale3h
authored and
fabaff
committed
[WIP] Standards/Style Guide for Documentation of Home Assistant (home-assistant#3461)
* Initial list of ideas for documentation standards * Add more points * Rename files * Create new section for Documentation and split content * Fixes (Links, content and alike)
1 parent 82dea44 commit ba6e507

File tree

5 files changed

+229
-153
lines changed

5 files changed

+229
-153
lines changed

‎source/_includes/asides/developers_navigation.html

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,8 +107,14 @@ <h1 class="title delta">Development Guide</h1>
107107
<li>{% active_link /developers/server_sent_events/ Server-sent events %}</li>
108108
</ul>
109109
</li>
110+
<li>
111+
{% active_link /developers/documentation/ Website/Documentation %}
112+
<ul>
113+
<li>{% active_link /developers/documentation/standards/ Standards %}</li>
114+
<li>{% active_link /developers/documentation/create_page/ Create a new page %}</li>
115+
</ul>
116+
</li>
110117
<li>{% active_link /developers/helpers/ Online helpers %}</li>
111-
<li>{% active_link /developers/website/ Website/Documentation %}</li>
112118
<li>{% active_link /developers/releasing/ Releasing %}</li>
113119
<li>{% active_link /developers/maintenance/ Maintenance %}</li>
114120
<li>

‎source/developers/documentation/create_page.markdown

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
layout: page
3+
title: "Create a new page"
4+
description: "Create a new page for the documentation"
5+
date: 2015-06-17 08:00
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](/components/) and the [Examples section](/cookbook/) are generated automatically, so there is no need to add a link to those pages.
13+
14+
Please honor the [Standards](/developers/documentation/standards/) we have for the documentation.
15+
16+
If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers.
17+
18+
```text
19+
---
20+
layout: page
21+
title: "Awesome Sensor"
22+
description: "home-assistant.io web presence"
23+
date: 2015-06-17 08:00
24+
sidebar: true
25+
comments: false
26+
sharing: true
27+
footer: true
28+
ha_release: "0.38"
29+
ha_category: Sensor
30+
---
31+
32+
Content...Written in markdown.
33+
34+
{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
35+
...
36+
```
37+
38+
There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation.
39+
40+
A couple of points to remember:
41+
42+
- Document the needed steps to retrieve API keys or access token for the third party service or device if needed.
43+
- If you're adding a new component, for the `ha_release` part of the header, just increment of the current release. If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`.
44+
- `ha_category:` is needed to list the platform or component in the appropriate category on the website.
45+
46+
### {% linkable_title Configuration %}
47+
48+
Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file.
49+
50+
The **Configuration Variables** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag.
51+
52+
53+
```text
54+
{% raw %}
55+
{% configuration %}
56+
api_key:
57+
description: The API key to access the service.
58+
required: true
59+
type: string
60+
name:
61+
description: Name to use in the frontend.
62+
required: false
63+
type: string
64+
{% endconfiguration %}
65+
{% endraw %}
66+
```
67+
68+
- **`description:`**: That the variable is about.
69+
- **`required:`**: If the variable is required.
70+
```text
71+
required: true #=> Required
72+
required: false #=> Optional
73+
required: inclusive #=> Inclusive
74+
required: exclusive #=> Exclusive
75+
required: any string here #=> Any string here
76+
```
77+
- **`type:`**: The type of the variable. Allowed entries: `string`, `int` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example).
78+
79+
### {% linkable_title Embedding Code %}
80+
81+
You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in {% raw %}`{% endraw %}.
82+
83+
When you're writing code that is to be executed on the terminal, prefix it with `$`.
84+
85+
### {% linkable_title Templates %}
86+
87+
For the [configuration templating](/topics/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](/developers/documentation/standards/) for further details.
88+
89+
If you are don't escape templates then they will be rendered and appear blank on the website.
90+
91+
### {% linkable_title HTML %}
92+
93+
The direct usage of HTML is supported but not recommended. The note boxes are an exception.
94+
95+
```html
96+
<p class='note warning'>
97+
You need to enable telnet on your router.
98+
</p>
99+
```
100+
101+
### {% linkable_title Redirects %}
102+
If you rename or move an existing platform or component, create the redirect. Add the old location of the page to the header of the new one.
103+
104+
```text
105+
---
106+
...
107+
redirect_from: /getting-started/android/
108+
---
109+
```
110+
111+
### {% linkable_title Images, icons, and logos %}
112+
113+
The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent.
114+
115+
| Type | Location |
116+
| :----------- |:----------------------------------------------|
117+
| logos | source/images/supported_brands |
118+
| blog | source/images/blog |
119+
| screenshots | source/images/components |
120+
121+
Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).

‎source/developers/documentation/index.markdown

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
layout: page
3+
title: "Documentation Home Assistant"
4+
description: "home-assistant.io web presence for the documentation"
5+
date: 2015-06-17 08:00
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
redirect: /developers/website/
11+
---
12+
13+
The website you are reading now is the home of Home Assistant: [https://home-assistant.io](https://home-assistant.io). This is the place where we provide documentation and additional details about Home Assistant for end users and developers.
14+
15+
home-assistant.io is built using [Jekyll](http://github.com/mojombo/jekyll) and [these available dependencies](https://pages.github.com/versions/). The pages are written in [markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know about HTML.
16+
17+
You can use the "**Edit this page on GitHub**" link to edit pages without creating a fork. Keep in mind that you can't upload images while working this way.
18+
19+
For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a pull request.
20+
21+
To test your changes locally, you need to install **Ruby** and its dependencies (gems):
22+
23+
- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already.
24+
- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler`
25+
- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need.
26+
27+
Short cut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle`
28+
29+
Then you can work on the documentation:
30+
31+
- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.github.io).
32+
- Create/edit/update a page in the directory `source/_components/` for your platform/component.
33+
- Test your changes to home-assistant.io locally: run `rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000)
34+
- Create a Pull Request (PR) against the **next** branch of home-assistant.github.io if your documentation is a new feature, platform, or component.
35+
- Create a Pull Request (PR) against the **current** branch of home-assistant.github.io if you fix stuff, create Cookbook entries, or expand existing documentation.
36+
37+
<p class='note'>
38+
It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview.
39+
</p>
40+
<p class='note'>
41+
Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding:
42+
`ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine`
43+
</p>
44+

‎source/developers/documentation/standards.markdown

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
layout: page
3+
title: "Documentation Standards"
4+
description: "Standards for the creation and maintenance of documentation for Home Assistant."
5+
date: 2017-09-16 03:51
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation.
13+
14+
## {% linkable_title General Documentation %}
15+
16+
* The language of the documentation should be American-English.
17+
* Don't put two spaces after a period and avoid the "Oxford comma".
18+
* Be objective and not gender favoring, polarizing, race related or religion inconsiderate.
19+
* The case of brand names, services, protocols, components, and platforms must match its respective counterpart. E.g. "Z-Wave" **not** "Zwave", "Z-wave", "Z Wave" or "ZWave". Also, "Input Select" **not** "input select" or "Input select".
20+
* All headings should use the {% raw %}`{% linkable_title %}`{% endraw %} tag.
21+
22+
## {% linkable_title Component and Platform Pages %}
23+
24+
* The **Configuration Variables** section must use the {% raw %}`{% configuration %}`{% endraw %} tag.
25+
* Configuration variables must document the requirement status.
26+
* Configuration variables must document the default value, if any.
27+
* Configuration variables must document the accepted value types.
28+
* Use `[string, int]` for configuration variables that accept multiple types.
29+
* Use YAML sequence syntax in the sample code if it is supported.
30+
* All examples should be formatted to be included in `configuration.yaml` unless explicitly stated.
31+
* Component and platform names should be a link to their respective documentation pages.
32+
33+
## {% linkable_title Templates %}
34+
35+
* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the {% raw %}`{% raw %}`{% endraw %} tag.
36+
* Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`.
37+
* Use double quotes (`"`) for:
38+
* `friendly_name`
39+
* Single-line templates:
40+
* `value_template`
41+
* `level_template`
42+
* `icon_template`
43+
* Children of `data_template`
44+
* Use single quotes (`'`) for:
45+
* Strings inside of templates:
46+
* States
47+
* Entity IDs
48+
* `unit_of_measurement`
49+
* No whitespace around pipe character (`|`) for Jinja2 filters.
50+
* Single whitespace after Jinja2 opening delimiters ({% raw %}`{{`{% endraw %}).
51+
* Single whitespace before Jinja2 closing delimiters ({% raw %}`}}`{% endraw %}).
52+
* Do not quote values for:
53+
* `device_class`
54+
* `platform`
55+
* `condition`
56+
* `service`
57+

‎source/developers/website.markdown

Lines changed: 0 additions & 152 deletions
This file was deleted.

0 commit comments

Comments
 (0)