From 49a4e6b6d02914a078678bcdb05a9711b3394a3f Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 26 Jan 2019 12:11:09 +0100 Subject: [PATCH] Add details about component/platform docs (#170) --- docs/documentation_create_page.md | 17 +++++++++++++++++ docs/documentation_standards.md | 8 ++++---- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/documentation_create_page.md b/docs/documentation_create_page.md index b92c4e7e..7c5cd24d 100644 --- a/docs/documentation_create_page.md +++ b/docs/documentation_create_page.md @@ -48,6 +48,23 @@ A couple of points to remember: - Add screenshots to support the user where it makes sense. - Add the type of the device(s) (incl. firmware) you have tested when you know that there are multiple out there. +### Components and platforms + +If you have a component that is taking care of setting up platforms then you don't need to create a new page for every supported platform. Simply add all supported types to `ha_category:` and use `redirect_from:` to list the dummy URL of the platforms. + +```text +... +ha_category: + - DIY + - Binary Sensor + - Switch +redirect_from: + - /components/binary_sensor.raspihats/ + - /components/switch.raspihats/ +--- +... +``` + ### 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. diff --git a/docs/documentation_standards.md b/docs/documentation_standards.md index 9c2ee25f..db2cf19b 100644 --- a/docs/documentation_standards.md +++ b/docs/documentation_standards.md @@ -10,16 +10,16 @@ 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, 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 `{% linkable_title %}` tag. -* Do not use ALL CAPITALS for emphasis - use italics instead +* Do not use ALL CAPITALS for emphasis - use italics instead. ## Component and Platform Pages * The **Configuration Variables** section must use the `{% configuration %}` tag. -* Configuration variables must document the requirement status (`false` or `true`) +* Configuration variables must document the requirement status (`false` or `true`). * Configuration variables must document the default value, if any. -* Configuration variables must document the accepted value types (see [Configuration variables details](documentation_create_page.md#configuration)) +* Configuration variables must document the accepted value types (see [Configuration variables details](documentation_create_page.md#configuration)). * For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, int`). * 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.