signaltypes: Bare minimal async docs.

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

.readthedocs.yaml

@@ -1,22 +0,0 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-#
-# Settings in the readthedocs online dashboard will be ignored.
-
-# Required
-version: 2
-
-# Build documentation in the doc/main directory with Sphinx
-sphinx:
-   configuration: doc/main/conf.py
-
-# Build your docs in additional formats such as PDF
-formats:
-   - pdf
-
-# Set the version of Python and requirements required to build the docs
-python:
-   version: 3.8
-   install:
-   - requirements: rtd-requirements.txt

.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())

poetry.lock

@@ -612,8 +612,8 @@ test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"]
 [package.source]
 type = "git"
 url = "https://github.com/pybricks/sphinx.git"
-reference = "b00124cb"
-resolved_reference = "b00124cb07318fd6875f6d53e0b26e50c7dde597"
+reference = "cd277d09"
+resolved_reference = "cd277d098ea2df9c79f0a4cbce28a426ec4120bc"
 
 [[package]]
 name = "sphinx-rtd-theme"
@@ -833,4 +833,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "2257db817f98695b16f12009a95e9c11447b5ba2df438ae4058853fbcbd5d814"
+content-hash = "c3ac22f3861c372d4572b51aa6263a693a8c42a7fa77ff5e735fea3be0e3f15b"

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"