From 220f6e5f0b06b97e42020c1b253d5e1bdb0b46a0 Mon Sep 17 00:00:00 2001 From: DubhAd Date: Sat, 8 Sep 2018 16:36:36 +0100 Subject: [PATCH] Added details The standards just say "use a configuration block", with zero useful information on how to do that. Fixing that ;) --- docs/documentation_standards.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/documentation_standards.md b/docs/documentation_standards.md index fe21694e..4b0aa900 100644 --- a/docs/documentation_standards.md +++ b/docs/documentation_standards.md @@ -17,9 +17,9 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo ## Component and Platform Pages * The **Configuration Variables** section must use the `{% configuration %}` tag. -* Configuration variables must document the requirement status. +* 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. +* Configuration variables must document the accepted value types (`string`, `boolean`, `integer`, `list`) * 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. @@ -27,6 +27,18 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo * 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. +Example configuration block + +```yaml +{% configuration %} +some_key: + description: This is a description of what this key is for. + required: false + type: string, list + default: Optional default value - leave out if there isn't one +{% endconfiguration %} +``` + ## Templates * All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the `{% raw %}` tag.