From 58dad5feb4a1b3163a6de324ae0bbbd1c184eedc Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Tue, 16 Feb 2021 23:24:01 +1300
Subject: [PATCH] Make explicit examples for splitting and joining using
 partitions (#1008)

---
 components/light/partition.rst | 55 +++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/components/light/partition.rst b/components/light/partition.rst
index b12af2e29..d245d8fd6 100644
--- a/components/light/partition.rst
+++ b/components/light/partition.rst
@@ -10,9 +10,10 @@ The ``partition`` light platform allows you to combine multiple addressable ligh
 This platform also allows splitting up an addressable lights into multiple segments, so that
 segments can be individually controlled.
 
-Similarly, a single light strip can be partitioned into multiple partitions with this integration.
+Splitting a single LED strip
+----------------------------
 
-If you want to do this, you may run into strange behavior like that the original light entity (e.g., ``fastled_clockless``)
+If you want to split a strip, you may run into strange behavior like that the original light entity (e.g., ``fastled_clockless``)
 may be conflicting with the partition. For better control over which segments of the strip will overlap each other,
 mark the original ``light`` as ``internal: true``.
 
@@ -21,16 +22,54 @@ mark the original ``light`` as ``internal: true``.
     # Example configuration entry
     light:
       - platform: partition
-        name: "Partition Light"
+        name: "Partition Light 1"
         segments:
-          # Use first LED from the light with ID light1
+          # Use first 10 LEDs from the light with ID light1
           - id: light1
             from: 0
-            to: 0
-          # Use 10 leds from light with ID light2 starting 2nd LED
+            to: 9
+
+      - platform: partition
+        name: "Partition Light 2"
+        segments:
+          # Use LEDs 11-20 from the light with ID light1
+          - id: light1
+            from: 10
+            to: 19
+
+      # Example for light segment source
+      - platform: fastled_clockless
+        id: light1
+        # You may want (but don't need) this
+        internal: true
+        # Other settings
+
+Joining multiple LED strips into one
+------------------------------------
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    light:
+      - platform: partition
+        name: "Partition Light"
+        segments:
+          # Use first 10 LEDs from the light with ID light1
+          - id: light1
+            from: 0
+            to: 9
+          # Use first 10 LEDs from light with ID light2
+          # they become LEDs 11-20 in the joined partition
           - id: light2
-            from: 1
-            to: 10
+            from: 0
+            to: 9
+
+      # Example for light segment source
+      - platform: fastled_clockless
+        id: light1
+        # You may want (but don't need) this
+        internal: true
+        # Other settings
 
       # Example for light segment source
       - platform: fastled_clockless