pybricks.tools: Document hub_menu.

Fixes https://github.com/pybricks/pybricks-api/issues/144

doc/main/tools/index.rst

@@ -27,6 +27,13 @@ Input tools
 
 .. autofunction:: pybricks.tools.read_input_byte
 
+.. pybricks-requirements:: light-matrix
+
+.. autofunction:: pybricks.tools.hub_menu
+
+.. literalinclude::
+    ../../../examples/pup/tools/hub_menu.py
+
 Linear algebra tools
 --------------------
 

examples/pup/tools/hub_menu.py

@@ -0,0 +1,16 @@
+from pybricks.tools import hub_menu
+
+# This example assumes that you have three other programs in Pybricks Code,
+# called "fly_mission", "drive_mission", and "zigzag". This example creates a
+# menu that lets you pick which one to run.
+
+# Choose a letter.
+selected = hub_menu("F", "D", "Z")
+
+# Based on the selection, run a program.
+if selected == "F":
+    import fly_mission
+elif selected == "D":
+    import drive_mission
+elif selected == "Z":
+    import zigzag

jedi/tests/test_complete_import.py

@@ -157,6 +157,7 @@ def test_from_pybricks_tools_import():
     assert [c["insertText"] for c in completions] == [
         "cross",
         "DataLog",
+        "hub_menu",
         "Matrix",
         "read_input_byte",
         "StopWatch",

setup.cfg

@@ -1,6 +1,6 @@
 
 [flake8]
-exclude = .venv/,*.pyi,jedi/
+exclude = .venv/,*.pyi,jedi/,examples/pup/tools/hub_menu.py
 max-line-length = 88
 ignore = E203,E501,W503
 

src/pybricks/tools.py

@@ -234,6 +234,27 @@ def read_input_byte() -> Optional[int]:
     """
 
 
+def hub_menu(*symbols: int | str) -> int | str:
+    """
+    hub_menu(symbol1, symbol2, ...) -> int | str
+
+    Shows a menu on the hub display and waits for the user to select an item
+    using the buttons. Can be used in your own menu-program that lets you
+    choose which of your other programs to run.
+
+    Note that this is just a convenience function that combines the display,
+    buttons, and waits to make a simple menu. This means that it can be used
+    anywhere in a program, not just at the start.
+
+    Arguments:
+        symbol1 (int or str): The first symbol to show in the menu.
+        symbol2 (int or str): The second symbol, and so on...
+
+    Returns:
+        The selected symbol.
+    """
+
+
 # HACK: hide from jedi
 if TYPE_CHECKING:
     del Number