pybricks.parameters.Icon: Document it.

Fixes #107
pybricks · Nov 10, 2022 · d2b1b21 · d2b1b21
1 parent a236609
commit d2b1b21
Show file tree

Hide file tree

Showing 5 changed files with 274 additions and 3 deletions.
diff --git a/doc/common/extensions/requirements-static.py b/doc/common/extensions/requirements-static.py
@@ -24,8 +24,8 @@
     "movehub": {"movehub"} | FEATURES_SMALL,
     "cityhub": {"cityhub"} | FEATURES_MEDIUM,
     "technichub": {"technichub"} | FEATURES_MEDIUM,
-    "primehub": {"primehub", "inventorhub"} | FEATURES_LARGE,
-    "inventorhub": {"primehub", "inventorhub"} | FEATURES_LARGE,
+    "primehub": {"primehub", "inventorhub", "light-matrix"} | FEATURES_LARGE,
+    "inventorhub": {"primehub", "inventorhub", "light-matrix"} | FEATURES_LARGE,
     "essentialhub": {"essentialhub"} | FEATURES_LARGE,
 }
 

diff --git a/doc/main/hubs/primehub.rst b/doc/main/hubs/primehub.rst
@@ -177,13 +177,15 @@ Changing the display orientation
 .. literalinclude::
     ../../../examples/pup/hub_primehub/display_orientation_imu.py
 
+.. _make_icons:
+
 Making your own images
 **********************
 
 .. literalinclude::
     ../../../examples/pup/hub_primehub/display_matrix.py
 
-Combining images to make expressions
+Combining icons to make expressions
 ************************************
 
 .. literalinclude::

diff --git a/doc/main/parameters/icon.rst b/doc/main/parameters/icon.rst
@@ -0,0 +1,8 @@
+.. pybricks-requirements:: light-matrix
+
+Icon
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: pybricks.parameters.Icon
+
+    See the :ref:`make_icons` section for examples.
diff --git a/doc/main/parameters/index.rst b/doc/main/parameters/index.rst
@@ -13,6 +13,7 @@
    button
    color
    direction
+   icon
    port
    side
    stop
@@ -23,6 +24,8 @@
 
 .. pybricks-classlink:: Direction
 
+.. pybricks-classlink:: Icon
+
 .. pybricks-classlink:: Port
 
 .. pybricks-classlink:: Side

diff --git a/src/pybricks/parameters.py b/src/pybricks/parameters.py
@@ -185,39 +185,297 @@ class Side(_PybricksEnum):
 
 
 class Icon:
+    """Icons to display on a light matrix.
+
+    Each of the following attributes are matrices. This means you can scale
+    icons to adjust the brightness or add icons to make composites.
+    """
+
     UP: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | ⬜🟨🟨🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨🟨🟨⬜
+    | ⬜🟨🟨🟨⬜
+    """
     DOWN: _Matrix
+    """
+    | ⬜🟨🟨🟨⬜
+    | ⬜🟨🟨🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨🟨🟨⬜
+    | ⬜⬜🟨⬜⬜
+    """
     LEFT: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | ⬜🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨🟨🟨🟨
+    | ⬜⬜🟨⬜⬜
+    """
     RIGHT: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | 🟨🟨🟨🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨⬜
+    | ⬜⬜🟨⬜⬜
+    """
     ARROW_RIGHT_UP: _Matrix
+    """
+    | ⬜⬜🟨🟨🟨
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜🟨⬜🟨
+    | ⬜🟨⬜⬜⬜
+    | 🟨⬜⬜⬜⬜
+    """
     ARROW_RIGHT_DOWN: _Matrix
+    """
+    | 🟨⬜⬜⬜⬜
+    | ⬜🟨⬜⬜⬜
+    | ⬜⬜🟨⬜🟨
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜🟨🟨🟨
+    """
     ARROW_LEFT_UP: _Matrix
+    """
+    | 🟨🟨🟨⬜⬜
+    | 🟨🟨⬜⬜⬜
+    | 🟨⬜🟨⬜⬜
+    | ⬜⬜⬜🟨⬜
+    | ⬜⬜⬜⬜🟨
+    """
     ARROW_LEFT_DOWN: _Matrix
+    """
+    | ⬜⬜⬜⬜🟨
+    | ⬜⬜⬜🟨⬜
+    | 🟨⬜🟨⬜⬜
+    | 🟨🟨⬜⬜⬜
+    | 🟨🟨🟨⬜⬜
+    """
     ARROW_UP: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | ⬜🟨🟨🟨⬜
+    | 🟨⬜🟨⬜🟨
+    | ⬜⬜🟨⬜⬜
+    | ⬜⬜🟨⬜⬜
+    """
     ARROW_DOWN: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | ⬜⬜🟨⬜⬜
+    | 🟨⬜🟨⬜🟨
+    | ⬜🟨🟨🟨⬜
+    | ⬜⬜🟨⬜⬜
+    """
     ARROW_LEFT: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | ⬜🟨⬜⬜⬜
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨⬜⬜⬜
+    | ⬜⬜🟨⬜⬜
+    """
     ARROW_RIGHT: _Matrix
+    """
+    | ⬜⬜🟨⬜⬜
+    | ⬜⬜⬜🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | ⬜⬜⬜🟨⬜
+    | ⬜⬜🟨⬜⬜
+    """
     HAPPY: _Matrix
+    """
+    | 🟨🟨⬜🟨🟨
+    | 🟨🟨⬜🟨🟨
+    | ⬜⬜⬜⬜⬜
+    | 🟨⬜⬜⬜🟨
+    | ⬜🟨🟨🟨⬜
+    """
     SAD: _Matrix
+    """
+    | 🟨🟨⬜🟨🟨
+    | 🟨🟨⬜🟨🟨
+    | ⬜⬜⬜⬜⬜
+    | ⬜🟨🟨🟨⬜
+    | 🟨⬜⬜⬜🟨
+    """
     EYE_LEFT: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | 🟨🟨⬜⬜⬜
+    | 🟨🟨⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_RIGHT: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_LEFT_BLINK: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | 🟨🟨⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_RIGHT_BLINK: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_RIGHT_BROW: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_LEFT_BROW: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | 🟨🟨⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_LEFT_BROW_UP: _Matrix
+    """
+    | 🟨🟨⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     EYE_RIGHT_BROW_UP: _Matrix
+    """
+    | ⬜⬜⬜🟨🟨
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     HEART: _Matrix
+    """
+    | ⬜🟨⬜🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨🟨🟨⬜
+    | ⬜⬜🟨⬜⬜
+    """
     PAUSE: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜🟨⬜🟨⬜
+    | ⬜🟨⬜🟨⬜
+    | ⬜🟨⬜🟨⬜
+    | ⬜⬜⬜⬜⬜
+    """
     EMPTY: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     FULL: _Matrix
+    """
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    """
     SQUARE: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜🟨🟨🟨⬜
+    | ⬜🟨🟨🟨⬜
+    | ⬜🟨🟨🟨⬜
+    | ⬜⬜⬜⬜⬜
+    """
     TRIANGLE_RIGHT: _Matrix
+    """
+    | ⬜🟨⬜⬜⬜
+    | ⬜🟨🟨⬜⬜
+    | ⬜🟨🟨🟨⬜
+    | ⬜🟨🟨⬜⬜
+    | ⬜🟨⬜⬜⬜
+    """
     TRIANGLE_LEFT: _Matrix
+    """
+    | ⬜⬜⬜🟨⬜
+    | ⬜⬜🟨🟨⬜
+    | ⬜🟨🟨🟨⬜
+    | ⬜⬜🟨🟨⬜
+    | ⬜⬜⬜🟨⬜
+    """
     TRIANGLE_UP: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | ⬜⬜🟨⬜⬜
+    | ⬜🟨🟨🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | ⬜⬜⬜⬜⬜
+    """
     TRIANGLE_DOWN: _Matrix
+    """
+    | ⬜⬜⬜⬜⬜
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨🟨🟨⬜
+    | ⬜⬜🟨⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     CIRCLE: _Matrix
+    """
+    | ⬜🟨🟨🟨⬜
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | 🟨🟨🟨🟨🟨
+    | ⬜🟨🟨🟨⬜
+    """
     CLOCKWISE: _Matrix
+    """
+    | 🟨🟨🟨🟨⬜
+    | 🟨⬜⬜🟨⬜
+    | 🟨⬜⬜🟨⬜
+    | 🟨⬜🟨🟨🟨
+    | ⬜⬜⬜🟨⬜
+    """
     COUNTERCLOCKWISE: _Matrix
+    """
+    | ⬜🟨🟨🟨🟨
+    | ⬜🟨⬜⬜🟨
+    | ⬜🟨⬜⬜🟨
+    | 🟨🟨🟨⬜🟨
+    | ⬜🟨⬜⬜⬜
+    """
     TRUE: _Matrix
+    """
+    | ⬜⬜⬜⬜🟨
+    | ⬜⬜⬜🟨⬜
+    | 🟨⬜🟨⬜⬜
+    | ⬜🟨⬜⬜⬜
+    | ⬜⬜⬜⬜⬜
+    """
     FALSE: _Matrix
+    """
+    | 🟨⬜⬜⬜🟨
+    | ⬜🟨⬜🟨⬜
+    | ⬜⬜🟨⬜⬜
+    | ⬜🟨⬜🟨⬜
+    | 🟨⬜⬜⬜🟨
+    """