mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-18 23:06:58 +00:00
[WIP] Standards/Style Guide for Documentation of 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)
This commit is contained in:
Dale Higgs
Fabian Affolter
parent
82dea44109
commit
ba6e507456
@ -107,8 +107,14 @@
|
||||
<li>{% active_link /developers/server_sent_events/ Server-sent events %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
{% active_link /developers/documentation/ Website/Documentation %}
|
||||
<ul>
|
||||
<li>{% active_link /developers/documentation/standards/ Standards %}</li>
|
||||
<li>{% active_link /developers/documentation/create_page/ Create a new page %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>{% active_link /developers/helpers/ Online helpers %}</li>
|
||||
<li>{% active_link /developers/website/ Website/Documentation %}</li>
|
||||
<li>{% active_link /developers/releasing/ Releasing %}</li>
|
||||
<li>{% active_link /developers/maintenance/ Maintenance %}</li>
|
||||
<li>
|
||||
|
||||
121
source/developers/documentation/create_page.markdown
Normal file
121
source/developers/documentation/create_page.markdown
Normal file
@ -0,0 +1,121 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Create a new page"
|
||||
description: "Create a new page for the documentation"
|
||||
date: 2015-06-17 08:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
Please honor the [Standards](/developers/documentation/standards/) we have for the documentation.
|
||||
|
||||
If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers.
|
||||
|
||||
```text
|
||||
---
|
||||
layout: page
|
||||
title: "Awesome Sensor"
|
||||
description: "home-assistant.io web presence"
|
||||
date: 2015-06-17 08:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
ha_release: "0.38"
|
||||
ha_category: Sensor
|
||||
---
|
||||
|
||||
Content...Written in markdown.
|
||||
|
||||
{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
|
||||
...
|
||||
```
|
||||
|
||||
There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation.
|
||||
|
||||
A couple of points to remember:
|
||||
|
||||
- Document the needed steps to retrieve API keys or access token for the third party service or device if needed.
|
||||
- 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 `" "`.
|
||||
- `ha_category:` is needed to list the platform or component in the appropriate category on the website.
|
||||
|
||||
### {% linkable_title Configuration %}
|
||||
|
||||
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.
|
||||
|
||||
The **Configuration Variables** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag.
|
||||
|
||||
|
||||
```text
|
||||
{% raw %}
|
||||
{% configuration %}
|
||||
api_key:
|
||||
description: The API key to access the service.
|
||||
required: true
|
||||
type: string
|
||||
name:
|
||||
description: Name to use in the frontend.
|
||||
required: false
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- **`description:`**: That the variable is about.
|
||||
- **`required:`**: If the variable is required.
|
||||
```text
|
||||
required: true #=> Required
|
||||
required: false #=> Optional
|
||||
required: inclusive #=> Inclusive
|
||||
required: exclusive #=> Exclusive
|
||||
required: any string here #=> Any string here
|
||||
```
|
||||
- **`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).
|
||||
|
||||
### {% linkable_title Embedding Code %}
|
||||
|
||||
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 %}.
|
||||
|
||||
When you're writing code that is to be executed on the terminal, prefix it with `$`.
|
||||
|
||||
### {% linkable_title Templates %}
|
||||
|
||||
For the [configuration templating](/topics/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](/developers/documentation/standards/) for further details.
|
||||
|
||||
If you are don't escape templates then they will be rendered and appear blank on the website.
|
||||
|
||||
### {% linkable_title HTML %}
|
||||
|
||||
The direct usage of HTML is supported but not recommended. The note boxes are an exception.
|
||||
|
||||
```html
|
||||
<p class='note warning'>
|
||||
You need to enable telnet on your router.
|
||||
</p>
|
||||
```
|
||||
|
||||
### {% linkable_title Redirects %}
|
||||
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.
|
||||
|
||||
```text
|
||||
---
|
||||
...
|
||||
redirect_from: /getting-started/android/
|
||||
---
|
||||
```
|
||||
|
||||
### {% linkable_title Images, icons, and logos %}
|
||||
|
||||
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.
|
||||
|
||||
| Type | Location |
|
||||
| :----------- |:----------------------------------------------|
|
||||
| logos | source/images/supported_brands |
|
||||
| blog | source/images/blog |
|
||||
| screenshots | source/images/components |
|
||||
|
||||
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/).
|
||||
44
source/developers/documentation/index.markdown
Normal file
44
source/developers/documentation/index.markdown
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Documentation Home Assistant"
|
||||
description: "home-assistant.io web presence for the documentation"
|
||||
date: 2015-06-17 08:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
redirect: /developers/website/
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
To test your changes locally, you need to install **Ruby** and its dependencies (gems):
|
||||
|
||||
- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already.
|
||||
- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler`
|
||||
- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need.
|
||||
|
||||
Short cut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle`
|
||||
|
||||
Then you can work on the documentation:
|
||||
|
||||
- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.github.io).
|
||||
- Create/edit/update a page in the directory `source/_components/` for your platform/component.
|
||||
- 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)
|
||||
- Create a Pull Request (PR) against the **next** branch of home-assistant.github.io if your documentation is a new feature, platform, or component.
|
||||
- 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.
|
||||
|
||||
<p class='note'>
|
||||
It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview.
|
||||
</p>
|
||||
<p class='note'>
|
||||
Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding:
|
||||
`ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine`
|
||||
</p>
|
||||
|
||||
57
source/developers/documentation/standards.markdown
Normal file
57
source/developers/documentation/standards.markdown
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Documentation Standards"
|
||||
description: "Standards for the creation and maintenance of documentation for Home Assistant."
|
||||
date: 2017-09-16 03:51
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
## {% linkable_title General Documentation %}
|
||||
|
||||
* The language of the documentation should be American-English.
|
||||
* Don't put two spaces after a period and avoid the "Oxford comma".
|
||||
* Be objective and not gender favoring, polarizing, race related or religion inconsiderate.
|
||||
* 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".
|
||||
* All headings should use the {% raw %}`{% linkable_title %}`{% endraw %} tag.
|
||||
|
||||
## {% linkable_title Component and Platform Pages %}
|
||||
|
||||
* The **Configuration Variables** section must use the {% raw %}`{% configuration %}`{% endraw %} tag.
|
||||
* Configuration variables must document the requirement status.
|
||||
* Configuration variables must document the default value, if any.
|
||||
* Configuration variables must document the accepted value types.
|
||||
* Use `[string, int]` for configuration variables that accept multiple types.
|
||||
* Use YAML sequence syntax in the sample code if it is supported.
|
||||
* All examples should be formatted to be included in `configuration.yaml` unless explicitly stated.
|
||||
* Component and platform names should be a link to their respective documentation pages.
|
||||
|
||||
## {% linkable_title Templates %}
|
||||
|
||||
* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the {% raw %}`{% raw %}`{% endraw %} tag.
|
||||
* Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`.
|
||||
* Use double quotes (`"`) for:
|
||||
* `friendly_name`
|
||||
* Single-line templates:
|
||||
* `value_template`
|
||||
* `level_template`
|
||||
* `icon_template`
|
||||
* Children of `data_template`
|
||||
* Use single quotes (`'`) for:
|
||||
* Strings inside of templates:
|
||||
* States
|
||||
* Entity IDs
|
||||
* `unit_of_measurement`
|
||||
* No whitespace around pipe character (`|`) for Jinja2 filters.
|
||||
* Single whitespace after Jinja2 opening delimiters ({% raw %}`{{`{% endraw %}).
|
||||
* Single whitespace before Jinja2 closing delimiters ({% raw %}`}}`{% endraw %}).
|
||||
* Do not quote values for:
|
||||
* `device_class`
|
||||
* `platform`
|
||||
* `condition`
|
||||
* `service`
|
||||
|
||||
@ -1,152 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Website home-assistant.io"
|
||||
description: "home-assistant.io web presence"
|
||||
date: 2015-06-17 08:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
To test your changes locally, you need to install **Ruby** and its dependencies (gems):
|
||||
|
||||
- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already.
|
||||
- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler`
|
||||
- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need.
|
||||
|
||||
Short cut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle`
|
||||
|
||||
Then you can work on the documentation:
|
||||
|
||||
- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.github.io).
|
||||
- Create/edit/update a page in the directory `source/_components/` for your platform/component.
|
||||
- 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)
|
||||
- Create a Pull Request (PR) against the **next** branch of home-assistant.github.io if your documentation is a new feature, platform, or component.
|
||||
- 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.
|
||||
|
||||
<p class='note'>
|
||||
It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview.
|
||||
</p>
|
||||
<p class='note'>
|
||||
Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding:
|
||||
`ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine`
|
||||
</p>
|
||||
|
||||
### {% linkable_title Create a page %}
|
||||
|
||||
For a platform 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.
|
||||
|
||||
If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers.
|
||||
|
||||
```text
|
||||
---
|
||||
layout: page
|
||||
title: "Website home-assistant.io"
|
||||
description: "home-assistant.io web presence"
|
||||
date: 2015-06-17 08:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
ha_release: "0.38"
|
||||
---
|
||||
|
||||
Content...Written in markdown.
|
||||
|
||||
{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
|
||||
...
|
||||
```
|
||||
|
||||
There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation.
|
||||
|
||||
A couple of points to remember:
|
||||
|
||||
- Document the needed steps to retrieve API keys or access token for the third party service or device if needed.
|
||||
- Keep the configuration sample minimal by only adding the `Required` options. Full configuration details with further explanations should go into a separate section.
|
||||
- The description of all the configuration variables should contains information about the used defaults.
|
||||
- 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 `" "`.
|
||||
|
||||
### {% linkable_title Configuration %}
|
||||
|
||||
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.
|
||||
|
||||
The ***Configuration Variables*** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag.
|
||||
|
||||
|
||||
```text
|
||||
{% raw %}
|
||||
{% configuration %}
|
||||
api_key:
|
||||
description: The API key to access the service.
|
||||
required: true
|
||||
type: string
|
||||
name:
|
||||
description: Name to use in the frontend.
|
||||
required: false
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- **`description:`**: That the variable is about.
|
||||
- **`required:`**: If the variable is required.
|
||||
```text
|
||||
required: true #=> Required
|
||||
required: false #=> Optional
|
||||
required: inclusive #=> Inclusive
|
||||
required: exclusive #=> Exclusive
|
||||
required: any string here #=> Any string here
|
||||
```
|
||||
- **`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).
|
||||
|
||||
### {% linkable_title Embedding Code %}
|
||||
|
||||
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 %}.
|
||||
|
||||
When you're writing code that is to be executed on the terminal, prefix it with `$`.
|
||||
|
||||
### {% linkable_title Templates %}
|
||||
|
||||
For the [configuration templating](/topics/templating/) is [Jinja](http://jinja.pocoo.org/) used.
|
||||
|
||||
If you are using templates then those parts needs to be [escaped](http://stackoverflow.com/a/24102537). Otherwise they will be rendered and appear blank on the website.
|
||||
|
||||
### {% linkable_title HTML %}
|
||||
|
||||
The direct usage of HTML is supported but not recommended. The note boxes are an exception.
|
||||
|
||||
```html
|
||||
<p class='note warning'>
|
||||
You need to enable telnet on your router.
|
||||
</p>
|
||||
```
|
||||
|
||||
### {% linkable_title Redirects %}
|
||||
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.
|
||||
|
||||
```text
|
||||
---
|
||||
...
|
||||
redirect_from: /getting-started/android/
|
||||
---
|
||||
```
|
||||
|
||||
### {% linkable_title Images, icons, and logos %}
|
||||
|
||||
The images which are displayed on the pages are stored in various directories according to their purpose.
|
||||
|
||||
| Type | Location |
|
||||
| :----------- |:----------------------------------------------|
|
||||
| screenshots | source/images/screenshots |
|
||||
| logos | source/images/supported_brands |
|
||||
|
||||
Not everything (product, component, etc.) has a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).
|
||||
Loading…
x
Reference in New Issue
Block a user