From 476dd1d0e64192753f27ce8ba200b98b73fdb7bb Mon Sep 17 00:00:00 2001 From: Dale Higgs Date: Thu, 28 Sep 2017 16:51:21 -0500 Subject: [PATCH 1/5] Initial list of ideas for documentation standards --- source/_docs/standards.markdown | 58 +++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 source/_docs/standards.markdown diff --git a/source/_docs/standards.markdown b/source/_docs/standards.markdown new file mode 100644 index 000000000000..cb70eef21bbd --- /dev/null +++ b/source/_docs/standards.markdown @@ -0,0 +1,58 @@ +--- +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 case of brand names, services, protocols, components, and platforms must match its respective counterpart. + * Z-Wave (**not** Zwave, Z-wave, Z Wave, or ZWave) + * Zigbee (**not** ZigBee) + * iCloud (**not** Icloud, icloud, or ICloud) + * Pushover (**not** PushOver, pushover, or push over) + * OwnTracks (**not** Owntracks, ownTracks, owntracks, or own tracks) + * 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. +* All examples containing Jinja2 templates should be wrapped ***outside*** of the code markdown with {% raw %}`{% raw %}`{% endraw %} tag. +* Component and platform names should be a link to their respective documentation pages. +* 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` From 54d25cc6288bed7a51228a957d33172f48864858 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 29 Sep 2017 08:37:22 +0200 Subject: [PATCH 2/5] Add more points --- source/_docs/standards.markdown | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/source/_docs/standards.markdown b/source/_docs/standards.markdown index cb70eef21bbd..322461793f51 100644 --- a/source/_docs/standards.markdown +++ b/source/_docs/standards.markdown @@ -9,18 +9,19 @@ 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. +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. - * Z-Wave (**not** Zwave, Z-wave, Z Wave, or ZWave) + * Z-Wave (**not** Zwave, Z-wave, Z Wave or ZWave) * Zigbee (**not** ZigBee) - * iCloud (**not** Icloud, icloud, or ICloud) - * Pushover (**not** PushOver, pushover, or push over) - * OwnTracks (**not** Owntracks, ownTracks, owntracks, or own tracks) + * iCloud (**not** Icloud, icloud or ICloud) + * Pushover (**not** PushOver, pushover or push over) + * OwnTracks (**not** Owntracks, ownTracks, owntracks or own tracks) * Input Select (**not** input select or Input select) * All headings should use the {% raw %}`{% linkable_title %}`{% endraw %} tag. From 3fa78b7f15446a526657a395d64b770b97065b8a Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 9 Oct 2017 17:19:32 +0200 Subject: [PATCH 3/5] Rename files --- .../developers/{website.markdown => documentation/index.markdown} | 0 source/{_docs => developers/documentation}/standards.markdown | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename source/developers/{website.markdown => documentation/index.markdown} (100%) rename source/{_docs => developers/documentation}/standards.markdown (100%) diff --git a/source/developers/website.markdown b/source/developers/documentation/index.markdown similarity index 100% rename from source/developers/website.markdown rename to source/developers/documentation/index.markdown diff --git a/source/_docs/standards.markdown b/source/developers/documentation/standards.markdown similarity index 100% rename from source/_docs/standards.markdown rename to source/developers/documentation/standards.markdown From 373bc603ea8b16ea01e6aa47fd06cd7be1eeb4ea Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 9 Oct 2017 17:26:09 +0200 Subject: [PATCH 4/5] Create new section for Documentation and split content --- .../asides/developers_navigation.html | 8 +- .../documentation/create_page.markdown | 121 ++++++++++++++++++ .../developers/documentation/index.markdown | 12 +- .../documentation/standards.markdown | 16 +-- 4 files changed, 142 insertions(+), 15 deletions(-) create mode 100644 source/developers/documentation/create_page.markdown diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html index 432d06630b8a..a9b9a4b52c3e 100644 --- a/source/_includes/asides/developers_navigation.html +++ b/source/_includes/asides/developers_navigation.html @@ -107,8 +107,14 @@

Development Guide

  • {% active_link /developers/server_sent_events/ Server-sent events %}
    • +
  • + {% active_link /developers/documentation/ Website/Documentation %} +
      +
    • {% active_link /developers/documentation/standards Standards %}
      • +
    • {% active_link /developers/documentation/create_page Create a new page %}
      • +
    +
  • {% active_link /developers/helpers/ Online helpers %}
    • -
  • {% active_link /developers/website/ Website/Documentation %}
  • {% active_link /developers/releasing/ Releasing %}
  • {% active_link /developers/maintenance/ Maintenance %}
  • diff --git a/source/developers/documentation/create_page.markdown b/source/developers/documentation/create_page.markdown new file mode 100644 index 000000000000..0c19f2442a2b --- /dev/null +++ b/source/developers/documentation/create_page.markdown @@ -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 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 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 +

    + You need to enable telnet on your router. +

    +``` + +### {% 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/). diff --git a/source/developers/documentation/index.markdown b/source/developers/documentation/index.markdown index 705c2932ce03..89a99394ad77 100644 --- a/source/developers/documentation/index.markdown +++ b/source/developers/documentation/index.markdown @@ -1,12 +1,13 @@ --- layout: page -title: "Website home-assistant.io" -description: "home-assistant.io web presence" +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. @@ -142,11 +143,12 @@ 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. +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 | | :----------- |:----------------------------------------------| -| screenshots | source/images/screenshots | | logos | source/images/supported_brands | +| blog | source/images/blog | +| screenshots | source/images/components | -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/). +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/). diff --git a/source/developers/documentation/standards.markdown b/source/developers/documentation/standards.markdown index 322461793f51..a5d0a26c97e0 100644 --- a/source/developers/documentation/standards.markdown +++ b/source/developers/documentation/standards.markdown @@ -16,26 +16,23 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo * 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. - * Z-Wave (**not** Zwave, Z-wave, Z Wave or ZWave) - * Zigbee (**not** ZigBee) - * iCloud (**not** Icloud, icloud or ICloud) - * Pushover (**not** PushOver, pushover or push over) - * OwnTracks (**not** Owntracks, ownTracks, owntracks or own tracks) - * 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 {% raw %}`{% linkable_title %}`{% endraw %} tag. ## {% linkable_title Component and Platform Pages %} -* The ***Configuration Variables*** section must use the {% raw %}`{% configuration %}`{% endraw %} tag. +* 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. -* All examples containing Jinja2 templates should be wrapped ***outside*** of the code markdown with {% raw %}`{% raw %}`{% endraw %} tag. * 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` @@ -57,3 +54,4 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo * `platform` * `condition` * `service` + From b5de895bdfbefb5b04085b4c97ee8af40c8bdca3 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 9 Oct 2017 18:47:03 +0200 Subject: [PATCH 5/5] Fixes (Links, content and alike) --- .../asides/developers_navigation.html | 4 +- .../documentation/create_page.markdown | 4 +- .../developers/documentation/index.markdown | 110 ------------------ .../documentation/standards.markdown | 2 +- 4 files changed, 5 insertions(+), 115 deletions(-) diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html index a9b9a4b52c3e..632f09c5afd5 100644 --- a/source/_includes/asides/developers_navigation.html +++ b/source/_includes/asides/developers_navigation.html @@ -110,8 +110,8 @@

    Development Guide

  • {% active_link /developers/documentation/ Website/Documentation %}
      -
    • {% active_link /developers/documentation/standards Standards %}
      • -
    • {% active_link /developers/documentation/create_page Create a new page %}
      • +
    • {% active_link /developers/documentation/standards/ Standards %}
      • +
    • {% active_link /developers/documentation/create_page/ Create a new page %}
  • {% active_link /developers/helpers/ Online helpers %}
    • diff --git a/source/developers/documentation/create_page.markdown b/source/developers/documentation/create_page.markdown index 0c19f2442a2b..6f363393e3ff 100644 --- a/source/developers/documentation/create_page.markdown +++ b/source/developers/documentation/create_page.markdown @@ -11,7 +11,7 @@ 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 we have for the documentation. +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. @@ -84,7 +84,7 @@ 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 for further details. +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. diff --git a/source/developers/documentation/index.markdown b/source/developers/documentation/index.markdown index 89a99394ad77..03d6b2fa0d62 100644 --- a/source/developers/documentation/index.markdown +++ b/source/developers/documentation/index.markdown @@ -42,113 +42,3 @@ Site generated by `rake` is only available locally. If you are developing on a h `ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine`

    -### {% 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 -

    - You need to enable telnet on your router. -

    -``` - -### {% 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/). diff --git a/source/developers/documentation/standards.markdown b/source/developers/documentation/standards.markdown index a5d0a26c97e0..5445e7cd5ac3 100644 --- a/source/developers/documentation/standards.markdown +++ b/source/developers/documentation/standards.markdown @@ -16,7 +16,7 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo * 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". +* 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 %}