Add docs for scene editor (#11222)

* Add docs for scene editor

* Comments

source/_docs/scene.markdown

@@ -0,0 +1,88 @@
+---
+title: "Scenes"
+description: "Instructions on how to setup scenes within Home Assistant."
+---
+
+You can create scenes that capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red.
+
+```yaml
+# Example configuration.yaml entry
+scene:
+  - name: Romantic
+    entities:
+      light.tv_back_light: on
+      light.ceiling:
+        state: on
+        xy_color: [0.33, 0.66]
+        brightness: 200
+  - name: Movies
+    entities:
+      light.tv_back_light:
+        state: on
+        brightness: 125
+      light.ceiling: off
+      media_player.sony_bravia_tv:
+        state: on
+        source: HDMI 1
+        state: on
+```
+
+{% configuration %}
+name:
+  description: Friendly name of scene.
+  required: true
+  type: string
+entities:
+  description: Entities to control and their desired state.
+  required: true
+  type: list
+{% endconfiguration %}
+
+As you can see, there are two ways to define the states of each `entity_id`:
+
+- Define the `state` directly with the entity. Be aware, that `state` needs to be defined.
+- Define a complex state with its attributes. You can see all attributes available for a particular entity under `developer-tools -> state`.
+
+Scenes can be activated using the service `scene.turn_on` (there is no 'scene.turn_off' service).
+
+```yaml
+# Example automation
+automation:
+  trigger:
+    platform: state
+    entity_id: device_tracker.sweetheart
+    from: "not_home"
+    to: "home"
+  action:
+    service: scene.turn_on
+    entity_id: scene.romantic
+```
+
+## Applying a scene without defining it
+
+With the `scene.apply` service you are able to apply a scene without first defining it via configuration. Instead, you pass the states as part of the service data. The format of the data is the same as the `entities` field in a configuration.
+
+```yaml
+# Example automation
+automation:
+  trigger:
+    platform: state
+    entity_id: device_tracker.sweetheart
+    from: "not_home"
+    to: "home"
+  action:
+    service: scene.apply
+    data:
+      entities:
+        light.tv_back_light:
+          state: on
+          brightness: 100
+        light.ceiling: off
+        media_player.sony_bravia_tv:
+          state: on
+          source: HDMI 1
+```
+
+## Reloading scenes
+
+Whenever you make a change to your scene configuration, you can call the `scene.reload` service to reload the scenes.

source/_docs/scene/editor.markdown

@@ -0,0 +1,77 @@
+---
+title: "Scenes Editor"
+description: "Instructions on how to use the scenes editor."
+---
+
+In Home Assistant 0.102 we introduced the first version of our scene editor. If you just created a new configuration with Home Assistant, then you're all set! Go to the UI and enjoy.
+
+From the UI choose **Configuration** which is located in the sidebar, then click on **Scenes** to go to the scene editor. Press the **+** sign in the lower right corner to get started.
+
+Choose a meaningful name for your scene.
+
+<p class='img'>
+  <img src='/images/docs/scenes/editor.png' />
+</p>
+
+Select all the devices (and/or entities when in advanced mode) you want to include in your scene.
+The state of your devices will be saved, so it can be restored when you are finished creating your scene.
+Set the state of the devices to how you want them to be in your scene, this can be done by clicking on it and edit the state from the popup, or any other method that changes the state.
+On the moment you save the scene, all the states of your devices are stored in the scene.
+When you leave the editor the states of the devices are restored to the state from before you started editing.
+
+## Updating your configuration to use the editor
+
+First, check that you have activated the configuration editor.
+
+```yaml
+# Activate the configuration editor
+config:
+```
+
+The scene editor reads and writes to the file `scenes.yaml` in the root of your [configuration](/docs/configuration/) folder.
+Currently, both the name of this file and its location are fixed.
+Make sure that you have set up the scene integration to read from it:
+
+```yaml
+# Configuration.yaml example
+scene: !include scenes.yaml
+```
+
+If you still want to use your old scene section, add a label to the old entry:
+
+```yaml
+scene old:
+  - name: ...
+```
+
+You can use the `scene:` and `scene old:` sections at the same time:
+
+- `scene old:` to keep your manual designed scenes
+- `scene:` to save the scene created by the online editor
+
+```yaml
+scene: !include scenes.yaml
+scene old: !include_dir_merge_list scenes
+```
+
+## Migrating your scenes to `scenes.yaml`
+
+If you want to migrate your old scenes to use the editor, you'll have to copy them to `scenes.yaml`. Make sure that `scenes.yaml` remains a list! For each scene that you copy over, you'll have to add an `id`. This can be any string as long as it's unique.
+
+For example:
+
+```yaml
+# Example scenes.yaml entry
+- id: my_unique_id # <-- Required for editor to work.
+  name: Romantic
+  entities:
+    light.tv_back_light: on
+    light.ceiling:
+      state: on
+      xy_color: [0.33, 0.66]
+      brightness: 200
+```
+
+<div class='note'>
+Any comments in the YAML file will be lost and templates will be reformatted when you update an automation via the editor.
+</div>

source/_includes/asides/docs_navigation.html

@@ -1,7 +1,7 @@
 <section class="aside-module grid__item one-whole lap-one-half">
-  <div class='section'>
+  <div class="section">
     <h1 class="title delta">Topics</h1>
-    <ul class='divided sidebar-menu'>
+    <ul class="divided sidebar-menu">
       <li>
         <b>{% active_link /faq/ FAQ %}</b> |
         <b>{% active_link /docs/glossary/ Glossary %}</b>
@@ -11,18 +11,34 @@
         <ul>
           <li>{% active_link /hassio/ Hass.io %}</li>
           <li>{% active_link /docs/installation/updating/ Updating %}</li>
-          <li>{% active_link /docs/installation/troubleshooting/ Troubleshooting %}</li>
+          <li>
+            {% active_link /docs/installation/troubleshooting/ Troubleshooting
+            %}
+          </li>
         </ul>
       </li>
       <li>
         <b>{% active_link /docs/configuration/ Configuration %}</b>
         <ul>
           <li>{% active_link /docs/configuration/yaml/ YAML %}</li>
-          <li>{% active_link /docs/configuration/basic/ Basic information %}</li>
+          <li>
-          <li>{% active_link /docs/configuration/devices/ Setting up devices %}</li>
+            {% active_link /docs/configuration/basic/ Basic information %}
-          <li>{% active_link /docs/configuration/customizing-devices/ Customizing entities %}</li>
+          </li>
-          <li>{% active_link /docs/configuration/troubleshooting/ Troubleshooting %}</li>
+          <li>
-          <li>{% active_link /docs/configuration/securing/ Security Check Points %}</li>
+            {% active_link /docs/configuration/devices/ Setting up devices %}
+          </li>
+          <li>
+            {% active_link /docs/configuration/customizing-devices/ Customizing
+            entities %}
+          </li>
+          <li>
+            {% active_link /docs/configuration/troubleshooting/ Troubleshooting
+            %}
+          </li>
+          <li>
+            {% active_link /docs/configuration/securing/ Security Check Points
+            %}
+          </li>
         </ul>
       </li>
       <li>
@@ -30,25 +46,43 @@
         <ul>
           <li>{% active_link /docs/configuration/remote/ Remote access %}</li>
           <li>{% active_link /docs/configuration/packages/ Packages %}</li>
-          <li>{% active_link /docs/configuration/splitting_configuration/ Splitting up the configuration %}</li>
+          <li>
-          <li>{% active_link /docs/configuration/secrets/ Storing Secrets %}</li>
+            {% active_link /docs/configuration/splitting_configuration/
+            Splitting up the configuration %}
+          </li>
+          <li>
+            {% active_link /docs/configuration/secrets/ Storing Secrets %}
+          </li>
           <li>{% active_link /docs/configuration/templating/ Templating %}</li>
-          <li>{% active_link /docs/configuration/group_visibility/ Group Visibility %}</li>
+          <li>
-          <li>{% active_link /docs/configuration/platform_options/ Entity component platform options %}</li>
+            {% active_link /docs/configuration/group_visibility/ Group
+            Visibility %}
+          </li>
+          <li>
+            {% active_link /docs/configuration/platform_options/ Entity
+            component platform options %}
+          </li>
         </ul>
       </li>
       <li>
         <b>{% active_link /docs/authentication/ Authentication %}</b>
         <ul>
-          <li>{% active_link /docs/authentication/providers/ Auth Providers %}</li>
+          <li>
-          <li>{% active_link /docs/authentication/multi-factor-auth/ Multi Factor Auth %}</li>
+            {% active_link /docs/authentication/providers/ Auth Providers %}
+          </li>
+          <li>
+            {% active_link /docs/authentication/multi-factor-auth/ Multi Factor
+            Auth %}
+          </li>
         </ul>
       </li>
       <li>
         <b>Core objects</b>
         <ul>
           <li>{% active_link /docs/configuration/events/ Events %}</li>
-          <li>{% active_link /docs/configuration/state_object/ State Objects %}</li>
+          <li>
+            {% active_link /docs/configuration/state_object/ State Objects %}
+          </li>
         </ul>
       </li>
       <li>
@@ -60,14 +94,21 @@
           <li>{% active_link /docs/automation/condition/ Conditions %}</li>
           <li>{% active_link /docs/automation/action/ Actions %}</li>
           <li>{% active_link /docs/automation/templating/ Templates %}</li>
-          <li>{% active_link /docs/automation/troubleshooting/ Troubleshooting %}</li>
+          <li>
+            {% active_link /docs/automation/troubleshooting/ Troubleshooting %}
+          </li>
         </ul>
       </li>
       <li>
         <b>{% active_link /docs/frontend/ Frontend %}</b>
         <ul>
-          <li>{% active_link /docs/frontend/mobile/ Android/iOS Homescreen %}</li>
+          <li>
-          <li>{% active_link /docs/frontend/browsers/ Browser Compatibility List %}</li>
+            {% active_link /docs/frontend/mobile/ Android/iOS Homescreen %}
+          </li>
+          <li>
+            {% active_link /docs/frontend/browsers/ Browser Compatibility List
+            %}
+          </li>
           <li>{% active_link /lovelace Lovelace UI %}</li>
         </ul>
       </li>
@@ -87,6 +128,13 @@
           <li>{% active_link /docs/scripts/editor/ Editor %}</li>
         </ul>
       </li>
+      <li>
+        <b>{% active_link /docs/scene/ Scenes %}</b>
+        <ul>
+          <li>{% active_link /docs/scene/editor/ Editor %}</li>
+          <li>{% active_link /docs/scene/scenegen/ scenegen %}</li>
+        </ul>
+      </li>
       <li>
         <b>{% active_link /docs/tools/ Tools and Helpers %}</b>
         <ul>
@@ -102,21 +150,40 @@
       <li>
         <b>{% active_link /docs/security/ Security %}</b>
         <ul>
-          <li>{% active_link /docs/security/webserver/ Web server fingerprint %}</li>
+          <li>
+            {% active_link /docs/security/webserver/ Web server fingerprint %}
+          </li>
           <li>{% active_link /docs/security/porosity/ Porosity %}</li>
         </ul>
       </li>
       <li>
         <b>{% active_link /docs/z-wave/ Z-Wave %}</b>
         <ul>
-          <li>{% active_link /docs/z-wave/installation/ Configuring the Z-Wave component %}</li>
+          <li>
+            {% active_link /docs/z-wave/installation/ Configuring the Z-Wave
+            component %}
+          </li>
           <li>{% active_link /docs/z-wave/adding/ Adding devices %}</li>
-          <li>{% active_link /docs/z-wave/control-panel/ The Z-Wave control panel %}</li>
+          <li>
+            {% active_link /docs/z-wave/control-panel/ The Z-Wave control panel
+            %}
+          </li>
           <li>{% active_link /docs/z-wave/controllers/ Controllers %}</li>
-          <li>{% active_link /docs/z-wave/devices/ Devices %} and {% active_link /docs/z-wave/entities/ Entities %}</li>
+          <li>
-          <li>{% active_link /docs/z-wave/query-stage/ Query Stages %} for devices</li>
+            {% active_link /docs/z-wave/devices/ Devices %} and {% active_link
-          <li>{% active_link /docs/z-wave/device-specific/ Device Specific %} configuration</li>
+            /docs/z-wave/entities/ Entities %}
-          <li>{% active_link /docs/z-wave/events/ Events %} and {% active_link /docs/z-wave/services/ Services %}</li>
+          </li>
+          <li>
+            {% active_link /docs/z-wave/query-stage/ Query Stages %} for devices
+          </li>
+          <li>
+            {% active_link /docs/z-wave/device-specific/ Device Specific %}
+            configuration
+          </li>
+          <li>
+            {% active_link /docs/z-wave/events/ Events %} and {% active_link
+            /docs/z-wave/services/ Services %}
+          </li>
         </ul>
       </li>
       <li>
@@ -126,7 +193,10 @@
           <li>{% active_link /docs/mqtt/certificate/ Certificate %}</li>
           <li>{% active_link /docs/mqtt/discovery/ Discovery %}</li>
           <li>{% active_link /docs/mqtt/service/ Publish service %}</li>
-          <li>{% active_link /docs/mqtt/birth_will/ Birth and last will messages %}</li>
+          <li>
+            {% active_link /docs/mqtt/birth_will/ Birth and last will messages
+            %}
+          </li>
           <li>{% active_link /docs/mqtt/testing/ Testing your setup %}</li>
           <li>{% active_link /docs/mqtt/logging/ Logging %}</li>
           <li>{% active_link /docs/mqtt/processing_json/ Processing JSON %}</li>
@@ -135,21 +205,52 @@
       <li>
         <b>{% active_link /docs/ecosystem/ios/ iOS %}</b>
         <ul>
-          <li>{% active_link /docs/ecosystem/ios/notifications/basic/ Basic notifications %}</li>
+          <li>
+            {% active_link /docs/ecosystem/ios/notifications/basic/ Basic
+            notifications %}
+          </li>
           <ul>
-            <li>{% active_link /docs/ecosystem/ios/notifications/sounds/ Sounds %}</li>
+            <li>
-            <li>{% active_link /docs/ecosystem/ios/notifications/architecture/ Architecture %}</li>
+              {% active_link /docs/ecosystem/ios/notifications/sounds/ Sounds %}
-            <li>{% active_link /docs/ecosystem/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}</li>
+            </li>
+            <li>
+              {% active_link /docs/ecosystem/ios/notifications/architecture/
+              Architecture %}
+            </li>
+            <li>
+              {% active_link
+              /docs/ecosystem/ios/notifications/privacy_security_rate_limits/
+              Privacy, rate limiting and security %}
+            </li>
           </ul>
           <li>Advanced notifications</li>
           <ul>
-            <li>{% active_link /docs/ecosystem/ios/notifications/attachments/ Attachments %}</li>
+            <li>
-            <li>{% active_link /docs/ecosystem/ios/notifications/content_extensions/ Dynamic content %}</li>
+              {% active_link /docs/ecosystem/ios/notifications/attachments/
-            <li>{% active_link /docs/ecosystem/ios/notifications/actions/ Actionable notifications %}</li>
+              Attachments %}
-            <li>{% active_link /docs/ecosystem/ios/notifications/requesting_location_updates/ Requesting location updates %}</li>
+            </li>
+            <li>
+              {% active_link
+              /docs/ecosystem/ios/notifications/content_extensions/ Dynamic
+              content %}
+            </li>
+            <li>
+              {% active_link /docs/ecosystem/ios/notifications/actions/
+              Actionable notifications %}
+            </li>
+            <li>
+              {% active_link
+              /docs/ecosystem/ios/notifications/requesting_location_updates/
+              Requesting location updates %}
+            </li>
           </ul>
-          <li>{% active_link /docs/ecosystem/ios/location/ Location Tracking %}</li>
+          <li>
-          <li>{% active_link /docs/ecosystem/ios/integration/ Integration with other apps %}</li>
+            {% active_link /docs/ecosystem/ios/location/ Location Tracking %}
+          </li>
+          <li>
+            {% active_link /docs/ecosystem/ios/integration/ Integration with
+            other apps %}
+          </li>
         </ul>
       </li>
       <li>
@@ -158,8 +259,12 @@
           <li>
             {% active_link /docs/autostart/ Autostart %}
             <ul>
-              <li>{% active_link /docs/autostart/systemd/ systemd (Linux) %}</li>
+              <li>
-              <li>{% active_link /docs/autostart/upstart/ Upstart (Linux) %}</li>
+                {% active_link /docs/autostart/systemd/ systemd (Linux) %}
+              </li>
+              <li>
+                {% active_link /docs/autostart/upstart/ Upstart (Linux) %}
+              </li>
               <li>{% active_link /docs/autostart/init.d/ init.d (Linux) %}</li>
               <li>{% active_link /docs/autostart/macos/ macOS %}</li>
               <li>{% active_link /docs/autostart/synology/ Synology NAS %}</li>
@@ -175,11 +280,21 @@
             {% active_link /docs/ecosystem/notebooks/ Notebooks %}
             <ul>
               <li>{% active_link /docs/ecosystem/notebooks/ Introduction %}</li>
-              <li>{% active_link /docs/ecosystem/notebooks/installation/ Installation %}</li>
+              <li>
+                {% active_link /docs/ecosystem/notebooks/installation/
+                Installation %}
+              </li>
               <li>{% active_link /docs/ecosystem/notebooks/graph/ Graph %}</li>
-              <li>{% active_link /docs/ecosystem/notebooks/api/ Home Assistant API %}</li>
+              <li>
-              <li>{% active_link /docs/ecosystem/notebooks/database/ Database %}</li>
+                {% active_link /docs/ecosystem/notebooks/api/ Home Assistant API
-              <li>{% active_link /docs/ecosystem/notebooks/stats/ Statistics %}</li>
+                %}
+              </li>
+              <li>
+                {% active_link /docs/ecosystem/notebooks/database/ Database %}
+              </li>
+              <li>
+                {% active_link /docs/ecosystem/notebooks/stats/ Statistics %}
+              </li>
             </ul>
           </li>
           <li>
@@ -189,30 +304,56 @@
               <li>{% active_link /docs/ecosystem/caddy/ Caddy Server %}</li>
               <li>{% active_link /docs/ecosystem/haproxy/ HAProxy %}</li>
               <li>{% active_link /docs/ecosystem/nginx/ NGINX %}</li>
-              <li>{% active_link /docs/ecosystem/nginx_subdomain/ NGINX with subdomain%}</li>
+              <li>
+                {% active_link /docs/ecosystem/nginx_subdomain/ NGINX with
+                subdomain%}
+              </li>
               <li>{% active_link /docs/ecosystem/tor/ Tor Onion Service %}</li>
             </ul>
           </li>
           <li>
             {% active_link /docs/ecosystem/certificates/ Certificates %}
             <ul>
-              <li>{% active_link /docs/ecosystem/certificates/tls_self_signed_certificate/ Self-signed certificate %}</li>
+              <li>
-              <li>{% active_link /docs/ecosystem/certificates/tls_domain_certificate/ Certificate domain owners %}</li>
+                {% active_link
-              <li>{% active_link /docs/ecosystem/certificates/lets_encrypt/ Let's Encrypt (detailed) %}</li>
+                /docs/ecosystem/certificates/tls_self_signed_certificate/
+                Self-signed certificate %}
+              </li>
+              <li>
+                {% active_link
+                /docs/ecosystem/certificates/tls_domain_certificate/ Certificate
+                domain owners %}
+              </li>
+              <li>
+                {% active_link /docs/ecosystem/certificates/lets_encrypt/ Let's
+                Encrypt (detailed) %}
+              </li>
             </ul>
           </li>
           <li>
             Backup
             <ul>
-              <li>{% active_link /docs/ecosystem/backup/backup_github/ Backup to GitHub %}</li>
+              <li>
-              <li>{% active_link /docs/ecosystem/backup/backup_dropbox/ Backup to Dropbox %}</li>
+                {% active_link /docs/ecosystem/backup/backup_github/ Backup to
-              <li>{% active_link /docs/ecosystem/backup/backup_usb/ Backup to USB device %}</li>
+                GitHub %}
+              </li>
+              <li>
+                {% active_link /docs/ecosystem/backup/backup_dropbox/ Backup to
+                Dropbox %}
+              </li>
+              <li>
+                {% active_link /docs/ecosystem/backup/backup_usb/ Backup to USB
+                device %}
+              </li>
             </ul>
           </li>
-          <li>{% active_link /docs/ecosystem/scenegen/ scenegen %}</li>
           <li>{% active_link /docs/ecosystem/synology/ Synology %}</li>
-          <li>{% active_link /docs/ecosystem/hass-configurator/ HASS Configurator %}</li>
+          <li>
+            {% active_link /docs/ecosystem/hass-configurator/ HASS Configurator
+            %}
+          </li>
         </ul>
+      </li>
     </ul>
   </div>
 </section>