signaltypes: Bare minimal async docs.

This is nowhere near complete, but provides handles to start documenting async for the relevant methods.

.readthedocs.yml

@@ -19,7 +19,6 @@ build:
 # Build documentation in the doc/main/ directory with Sphinx
 sphinx:
   configuration: doc/main/conf.py
-  fail_on_warning: true
 
 # Optionally build your docs in additional formats such as PDF
 formats:

doc/main/signaltypes.rst

@@ -293,3 +293,25 @@ though the *hub* accelerates backward.
    and other creations, by noting which way the top and
    front :class:`Side <Side>` of the hub are pointing. The example
    on the left is the default configuration.
+
+.. class:: await
+
+Multitasking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pybricks supports cooperative multitasking using the ``async`` and ``await``
+keywords. This allows operations that normally take some time to complete, to
+run in parallel with other operations.
+
+Whenever you see the word ``await`` in the documentation, this means that the
+method or function supports multitasking.
+
+The following example shows how to use multitasking to make a robot drive
+forward, then turn and move a gripper at the same time, and then drive
+backward.
+
+.. literalinclude::
+    ../../examples/pup/robotics/drivebase_async.py
+
+If you don't use multitasking, you can ignore the ``await`` keyword and write
+programs as usual.

examples/pup/robotics/drivebase_async.py

@@ -0,0 +1,27 @@
+from pybricks.pupdevices import Motor
+from pybricks.parameters import Direction, Port
+from pybricks.robotics import DriveBase
+from pybricks.tools import multitask, run_task
+
+# Set up all devices.
+left = Motor(Port.A, Direction.COUNTERCLOCKWISE)
+right = Motor(Port.B)
+gripper = Motor(Port.C)
+drive_base = DriveBase(left, right, 56, 114)
+
+
+# Move the gripper up and down.
+async def move_gripper():
+    await gripper.run_angle(500, -90)
+    await gripper.run_angle(500, 90)
+
+
+# Drive forward, turn move gripper at the same time, and drive backward.
+async def main():
+    await drive_base.straight(250)
+    await multitask(drive_base.turn(90), move_gripper())
+    await drive_base.straight(-250)
+
+
+# Runs the main program from start to finish.
+run_task(main())

pyproject.toml

@@ -34,7 +34,7 @@ doc8 = "^0.8.1"
 flake8 = "^4.0"
 
 [tool.poetry.group.doc.dependencies]
-Sphinx = { git = "https://github.com/pybricks/sphinx.git", rev = "b00124cb" }
+Sphinx = { git = "https://github.com/pybricks/sphinx.git", rev = "cd277d09" }
 sphinx-rtd-theme = "^1.0.0"
 toml = "^0.10.0"