pybricks/builtins: update Speaker docs

doc/api/hubs_ev3brick.inc

@@ -20,19 +20,21 @@
 
     .. rubric:: Using the speaker
 
-    .. automethod:: pybricks._instances.speaker.volume
+    .. todo:: The following method is not yet implemented
 
-    .. automethod:: pybricks._instances.speaker.beep
+    .. automethod:: pybricks.hubs::EV3Brick.speaker.volume
 
-    .. automethod:: pybricks._instances.speaker.play
+    .. automethod:: pybricks.hubs::EV3Brick.speaker.beep
 
-    .. todo:: The following functionality is not yet implemented
+    .. automethod:: pybricks.hubs::EV3Brick.speaker.play_notes
 
-    .. automethod:: pybricks._instances.speaker.say
+    .. automethod:: pybricks.hubs::EV3Brick.speaker.play_file
 
-    .. todo:: The following functionality is not yet implemented
+    .. automethod:: pybricks.hubs::EV3Brick.speaker.say
 
-    .. automethod:: pybricks._instances.speaker.set_voice_settings
+    .. todo:: The following method is not yet implemented
+
+    .. automethod:: pybricks.hubs::EV3Brick.speaker.set_voice_settings
 
 
     .. rubric:: Using the screen

doc/common/conf.py

@@ -25,6 +25,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 from pybricks import _version  # noqa E402
 from pybricks.hubs import EV3Brick  # noqa E402
 from pybricks.resources import Image  # noqa E402
+from pybricks.builtins import Speaker  # noqa E402
 
 # ON_RTD is whether we are on readthedocs.org
 # this line of code grabbed from docs.readthedocs.org
@@ -110,6 +111,7 @@ nitpick_ignore = [
     ('py:class', 'dict'),
     ('py:class', 'float'),
     ('py:class', 'int'),
+    ('py:class', 'iter'),
     ('py:class', 'list'),
     ('py:class', 'object'),
     ('py:class', 'str'),
@@ -288,9 +290,12 @@ def find_obj(self, env, modname, classname, name, type, searchmode=0):
                 modname = 'pybricks.resources'
             else:
                 classname = 'EV3Brick.screen'
+        elif classname == 'speaker':
+            classname = 'EV3Brick.speaker'
     return base_find_obj(self, env, modname, classname, name, type, searchmode)
 
 
 PythonDomain.find_obj = find_obj
 
 EV3Brick.screen = Image
+EV3Brick.speaker = Speaker

pybricks/_instances.py

@@ -1,6 +1,6 @@
 """Sphinx workaround to document instance attributes such as self.light"""
 
-from .builtins import Motor, Speaker, Battery, ColorLight, KeyPad, LightArray
+from .builtins import Motor, Battery, ColorLight, KeyPad, LightArray
 from .parameters import Direction, Stop
 from types import ModuleType
 
@@ -23,8 +23,6 @@ buttons = make_instance(KeyPad)
 
 battery = make_instance(Battery)
 
-speaker = make_instance(Speaker)
-
 
 class Motor(Motor):
     """Generic class to control motors with built-in rotation sensors."""

pybricks/builtins.py

@@ -338,17 +338,50 @@ class Speaker():
         """Play a beep/tone.
 
         Arguments:
-            frequency (:ref:`frequency`): Frequency of the beep
-                                          (*Default*: 500).
-            duration (:ref:`time`): Duration of the beep (*Default*: 100).
+            frequency (:ref:`frequency`):
+                Frequency of the beep (*Default*: 500). Frequencies below 100
+                are treated as 100.
+            duration (:ref:`time`):
+                Duration of the beep (*Default*: 100). If the duration is less
+                than 0, then the method returns immediately and the frequency
+                play continues to play indefinitely.
         """
         pass
 
-    def play(self, file_name):
+    def play_notes(self, notes, tempo=120):
+        """Play a sequence of notes.
+
+        Notes are strings with the following format:
+
+        - The first character is the name of the note, ``A`` to ``G`` or ``R``
+          for a rest.
+        - Note names can also include an accidental ``#`` (sharp) or ``b``
+          (flat). ``B#``/``Cb`` and ``E#``/``Fb`` are not allowed.
+        - The note name is followed by the octave number ``2`` to ``8``. For
+          example ``C4`` is middle C. The octave changes to the next number at
+          the note C, for example, ``B3`` is the note below middle C (``C4``).
+        - The octave is followed by ``/`` and a number that indicates the size
+          of the note. For example ``/4`` is a quarter note, ``/8`` is an
+          eight note and so on.
+        - This can optionally followed by a ``.`` to make a dotted note.
+          Dotted notes are 1-1/2 times as long as notes without a dot.
+        - The note can optionally end with a ``_`` which is a tie or a slur.
+          This causes there to be no pause between this note and the next note.
+
+        Arguments:
+            notes (iter):
+                A sequence of notes to be played (see format above).
+            tempo (int):
+                Beats per minute where a quarter note is one beat.
+        """
+        pass
+
+    def play_file(self, file_name):
         """Play a sound file.
 
         Arguments:
-            file_name (str): Path to the sound file, including extension.
+            file_name (str):
+                Path to the sound file, including the file extension.
         """
 
         pass
@@ -356,6 +389,8 @@ class Speaker():
     def say(self, text):
         """Say a given text string.
 
+        The settings from :meth:`set_voice_settings` will affect the playback.
+
         Arguments:
             text (str): What to say.
         """
@@ -366,7 +401,7 @@ class Speaker():
         """Configure voice settings used by the ``say`` method.
 
         Arguments:
-            language (str)::
+            language (str):
                 - ``'en'`` (English)
                 - ``'nl'`` (Dutch)
                 - ``'de'`` (German)