doc/parameters/Color: add examples

examples/pup/parameters/color_advanced.py

@@ -0,0 +1,31 @@
+from pybricks.parameters import Color
+
+# Two colors are equal if their h, s, and v attributes are equal.
+if Color.BLUE == Color(240, 100, 100):
+    print("Yes, these colors are the same.")
+
+# You can scale colors to change their brightness value.
+red_dark = Color.RED * 0.5
+
+# You can shift colors to change their hue.
+red_shifted = Color.RED >> 30
+
+# Colors are immutable, so you can't change h, s, or v of an existing object.
+try:
+    Color.GREEN.h = 125
+except AttributeError:
+    print("Sorry, can't change the hue of an existing color object!")
+
+# But you can override builtin colors by defining a whole new color.
+Color.GREEN = Color(h=125)
+
+# You can access and store colors as class attributes, or as a dictionary.
+print(Color.BLUE)
+print(Color["BLUE"])
+print(Color["BLUE"] is Color.BLUE)
+print(Color)
+print([c for c in Color])
+
+# This allows you to update existing colors in a loop.
+for name in ("BLUE", "RED", "GREEN"):
+    Color[name] = Color(1, 2, 3)

examples/pup/parameters/color_basics.py

@@ -0,0 +1,23 @@
+from pybricks.parameters import Color
+
+# You can print colors. Colors may be obtained from the Color class, or
+# from sensors that return color measurements.
+print(Color.RED)
+
+# You can read hue, saturation, and value properties.
+print(Color.RED.h, Color.RED.s, Color.RED.v)
+
+# You can make your own colors. Saturation and value are 100 by default.
+my_green = Color(h=125)
+my_dark_green = Color(h=125, s=80, v=30)
+
+# When you print custom colors, you see exactly how they were defined.
+print(my_dark_green)
+
+# You can also add colors to the builtin colors.
+Color.MY_DARK_BLUE = Color(h=235, s=80, v=30)
+
+# When you add them like this, printing them only shows its name. But you can
+# still read h, s, v by reading its attributes.
+print(Color.MY_DARK_BLUE)
+print(Color.MY_DARK_BLUE.h, Color.MY_DARK_BLUE.s, Color.MY_DARK_BLUE.v)