doc/pupdevices/ColorSensor: add examples

doc/api/pupdevices.rst

@@ -181,18 +181,59 @@ Color Sensor
 .. figure:: ../api/images/sensor_color_lights_label.png
    :width: 70 %
 
+.. toggle-header::
+    :header: **Show/hide examples**
+
+
+    **Example 1: Measuring color and reflection**
+
+    .. literalinclude::
+        ../../pybricks-projects/snippets/pup/sensor_color/color_print.py
+
+
+    **Example 2: Waiting for a color**
+
+    .. literalinclude::
+        ../../pybricks-projects/snippets/pup/sensor_color/wait_for_color.py
+
 .. autoclass:: pybricks.pupdevices.ColorSensor
     :no-members:
 
     .. automethod:: pybricks.pupdevices.ColorSensor.color
 
-    .. automethod:: pybricks.pupdevices.ColorSensor.hsv
-
-    .. automethod:: pybricks.pupdevices.ColorSensor.color_map
+    .. automethod:: pybricks.pupdevices.ColorSensor.reflection
 
     .. automethod:: pybricks.pupdevices.ColorSensor.ambient
 
-    .. automethod:: pybricks.pupdevices.ColorSensor.reflection
+    .. rubric:: Advanced color sensing
+
+    .. toggle-header::
+        :header: **Show/hide examples**
+
+        **Example 1: Reading hue, saturation, and value**
+
+        .. literalinclude::
+            ../../pybricks-projects/snippets/pup/sensor_color/hsv.py
+
+
+        **Example 2: Modifying the default color map**
+
+        .. literalinclude::
+            ../../pybricks-projects/snippets/pup/sensor_color/color_map_modify.py
+
+        **Example 3: Providing a whole new color map**
+
+        .. literalinclude::
+            ../../pybricks-projects/snippets/pup/sensor_color/color_map_new.py
+
+        **Example 4: Reading ambient hue, saturation, value, and color**
+
+        .. literalinclude::
+            ../../pybricks-projects/snippets/pup/sensor_color/color_ambient.py
+
+    .. automethod:: pybricks.pupdevices.ColorSensor.hsv
+
+    .. automethod:: pybricks.pupdevices.ColorSensor.color_map
 
     .. rubric:: Built-in lights
 
@@ -200,6 +241,14 @@ Color Sensor
     light. If you use the sensor to measure something, the lights will
     be turned on or off as needed for the measurement.
 
+    .. toggle-header::
+        :header: **Show/hide examples**
+
+        **Example: Blinking the built-in lights**
+
+        .. literalinclude::
+            ../../pybricks-projects/snippets/pup/sensor_color/lights_blink.py
+
     .. automethod:: pybricks.pupdevices::ColorSensor.lights.on
 
     .. automethod:: pybricks.pupdevices::ColorSensor.lights.off