Updates documentation standards (#292)

docs/documentation_create_page.md

@@ -2,7 +2,7 @@
 title: "Create a new page"
 ---
 
-For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](https://www.home-assistant.io/components/) and the [Examples section](https://www.home-assistant.io/cookbook/) are generated automatically, so there is no need to add a link to those pages.
+For a platform or integration page, the fastest way is to make a copy of an existing page and edit it. The [Integration overview](https://www.home-assistant.io/components/) and the [Examples section](https://www.home-assistant.io/cookbook/) are generated automatically, so there is no need to add a link to those pages.
 
 Please honor the [Standards](documentation_standards.md) we have for the documentation.
 
@@ -10,35 +10,29 @@ If you start from scratch with a page, you need to add a header. Different secti
 
 ```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
 ha_iot_class: "Local Polling"
 ha_qa_scale: silver
+ha_config_flow: true
 ---
 
-Content... Written in markdown. 
+Content... Written in markdown.
 
-### {% linkable_title Linkable Header %}
+### Title Header
 ...
 ```
 
-Please keep in mind that if the `date:` entry is in the future then the page will not show up.
-
 Additional keys for the file header:
 
 - `logo`: Please check the separate section below.
 - `ha_release`: The release when the integration was included, e.g., "0.38". 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`: This entry is used to group the integration on the [Components overview](https://www.home-assistant.io/components/).
+- `ha_category`: This entry is used to group the integration on the [Integration overview](https://www.home-assistant.io/components/).
 - `ha_iot_class`: [IoT class](https://www.home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things) is the classifier for the device's behavior.
 - `ha_qa_scale`: [Quality scale](https://www.home-assistant.io/docs/quality_scale/) is the representation of the integration's quality.
+- `ha_config_flow`: Set to `true` if the integration has a [Data Entry Flow](https://developers.home-assistant.io/docs/en/data_entry_flow_index.html), omit otherwise.
 
 There are [pre-defined variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation.
 
@@ -96,7 +90,7 @@ required: any string here #=> Any string here
 
 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 back-ticks. 
 
-When you're writing code that is to be executed on the terminal, prefix it with `$`.
+When you're writing code that is to be executed on the terminal, do not prefix them with `$`, since this makes it hard to copy and paste the commands. However, an exception is made when there is a need to distinguish between typed commands and command output. In those cases, prefixing the commands with a `$` is required.
 
 ### Templates
 
@@ -109,9 +103,17 @@ If you are don't escape templates then they will be rendered and appear blank on
 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>
+<div class='note warning'>
+  You need to enable telnet on your router.
+</div>
+```
+
+Please note, if you want to use Markdown inside an HTML block, it has to be surrounded by a new line.
+
+```html
+<div class='note warning'>
+  You need to enable [**telnet**](https://en.wikipedia.org/wiki/Telnet) on your router.
+</div>
 ```
 
 ### Images, icons and logos
@@ -124,7 +126,7 @@ The images which are displayed on the pages are stored in various directories ac
 | 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/).
+Not everything (product, integration, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).
 
 ### Linking From The Sidebar
 

docs/documentation_index.md

@@ -24,10 +24,10 @@ To test your changes locally, you need to install **Ruby** and its dependencies
 
 Then you can work on the documentation:
 
-- Run `bundle exec rake generate` to generate the very first preview. This will take a couple of minutes.
-- Create/edit/update a page. The components/platforms documentation is located in `source/_components/`. `source/_docs/` contains the Home Assistant documentation itself.
+- Run `bundle exec rake generate` to generate the very first preview. This will take a minute.
+- Create/edit/update a page. The integration/platforms documentation is located in `source/_components/`. `source/_docs/` contains the Home Assistant documentation itself.
 - Test your changes to home-assistant.io locally: run `bundle exec rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000). While this command is working, any changes to a file are automatically detected and will update the affected pages. You will have to manually reload them in the browser though.
-- Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is a new feature, platform, or component.
+- Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is a new feature, platform, or integration.
 - Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
 
 The site generated by `bundle exec rake` is only available locally. If you are developing on a headless machine, use port forwarding:
@@ -38,10 +38,10 @@ $ ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine
 
 ## Speeding up site generation
 
-Every release we post long changelogs to the website. This slows down generation of the website significantly! We include some tools to temporarily exclude components and blog posts that you're not working on out of the way.
+Every release we post long changelogs to the website. This slows down generation of the website a bit. We've include some tools to temporarily exclude integrations and blog posts that you're not working on out of the way.
 
 ```bash
-bundle exec rake isolate[filename-of-blogpost-or-component]
+bundle exec rake isolate[filename-of-blogpost-or-integration]
 ```
 
 When you're done working on the site, run the following command to move the pages back again:

docs/documentation_standards.md

@@ -10,10 +10,10 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo
 * Don't put two spaces after a period and avoid the "Oxford comma".
 * There is no limit for the line length. You are allowed to write in a flowing text style. This will make it easier to use the GitHub online editor in the future.
 * 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".
+* The case of brand names, services, protocols, integrations 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".
 * Do not use ALL CAPITALS for emphasis - use italics instead.
 
-## Component and Platform Pages
+## Integration and Platform Pages
 
 * The **Configuration Variables** section must use the `{% configuration %}` tag.
 * Configuration variables must document the requirement status (`false` or `true`).
@@ -24,7 +24,7 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo
 * All examples should be formatted to be included in `configuration.yaml` unless explicitly stated.
   * Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`.
   * If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note.
-* Component and platform names should be a link to their respective documentation pages.
+* Integration and platform names should be a link to their respective documentation pages.
 
 Example configuration block
 
@@ -65,7 +65,7 @@ some_key:
 
 ## Renaming Pages
 
-It can happen that a component or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add  `redirect_from:` to the file header and let it point to the old location/name of the page. Please consider to add details, like release number or old component/platform name, to the page in a [note](/developers/documentation/create_page/#html).
+It can happen that a integration or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add  `redirect_from:` to the file header and let it point to the old location/name of the page. Please consider to add details, like release number or old integration/platform name, to the page in a [note](/developers/documentation/create_page/#html).
 
 ```text
 ---
@@ -106,7 +106,6 @@ automation:
 
 #### Multi-Line Template (Valid)
 
-
 ```yaml
 automation:
   ...
@@ -120,4 +119,3 @@ automation:
             It's just another door.
           {% endif %}
 ```
-