doc/common/conf: Format units in return type.

This formats return types so they don't look like tuples:

int: deg

If we can figure out how these nodes work, we can create proper links
and maybe use italics for the units or a slightly different font color.

doc/common/conf.py

@@ -27,6 +27,7 @@ from docutils import nodes
 from docutils.parsers.rst.directives import flag
 from docutils.parsers.rst import Directive
 from sphinx.application import Sphinx
+from sphinx.roles import XRefRole
 import toml
 
 TOP_DIR = os.path.abspath(os.path.join('..', '..'))
@@ -310,8 +311,26 @@ def on_missing_reference(app, env, node, contnode):
     # warnings when Sphinx tries to cross reference units like deg/s. For
     # consistency, we also treat units without special characters this way.
     for unit in ['deg', 'deg/s', 'mm/s', '%', 'mV', 'mA']:
-        if unit == contnode.rawsource or unit == str(contnode):
+        
+        # If they match on raw source, we are dealing with argument types.
+        if unit == contnode.rawsource:
+            # Return as-is to suppress missing cross reference warning. We
+            # could make this more fancy by returning an xref node that links
+            # to the signals page.
             return contnode
+        
+        # Return types are denoted as "int: deg"
+        try:
+            # Try to unpack the node.
+            ret_type, ret_unit = str(contnode).split(": ")
+        except ValueError:
+            # Not a valid format, so skip.
+            continue
+        
+        # If it's a match, we could format the node so it looks a bit nicer.
+        # For now just keep the colon notation as is.
+        if unit == ret_unit:
+            return nodes.Text(f"{ret_type}: {ret_unit}")
 
 
 def setup(app: Sphinx):

src/pybricks/_common.py

@@ -5,7 +5,7 @@
 speakers, and batteries."""
 
 from .parameters import Direction, Stop, Button, Port
-from typing import Union, Iterable, overload, Optional, Tuple
+from typing import Union, Iterable, overload, Optional, Tuple, Collection
 
 
 Number = Union[int, float]
@@ -240,11 +240,14 @@ class Motor(DCMotor):
     ``control`` attribute of the motor. See :ref:`control` for an overview
     of available methods."""
 
-    def __init__(self, port,
-                 positive_direction=Direction.CLOCKWISE,
-                 gears=None,
-                 reset_angle=True):
-        """
+    def __init__(
+        self,
+        port: Port,
+        positive_direction: Direction = Direction.CLOCKWISE,
+        gears: Optional[Union[Collection[int], Collection[Collection[int]]]] = None,
+        reset_angle: bool = True,
+    ):
+        """Motor(port, positive_direction=Direction.CLOCKWISE, gears=None, reset_angle=True)
 
         Arguments:
             port (Port): Port to which the motor is connected.
@@ -270,20 +273,23 @@ class Motor(DCMotor):
         """
         pass
 
-    def angle(self):
-        """Gets the rotation angle of the motor.
+    def angle(self) -> int:
+        """angle() -> int: deg
+
+        Gets the rotation angle of the motor.
 
         Returns:
-            :ref:`angle`: Motor angle.
-
+            Motor angle.
         """
         pass
 
-    def speed(self):
-        """Gets the speed of the motor.
+    def speed(self) -> int:
+        """speed() -> int: deg/s
+
+        Gets the speed of the motor.
 
         Returns:
-            :ref:`speed`: Motor speed.
+            Motor speed.
 
         """
         pass
@@ -360,7 +366,7 @@ class Motor(DCMotor):
 
     def run_until_stalled(self, speed, then=Stop.COAST, duty_limit=None):
         """
-        run_until_stalled(speed, then=Stop.COAST, duty_limit=None) -> int, deg
+        run_until_stalled(speed, then=Stop.COAST, duty_limit=None) -> int: deg
 
         Runs the motor at a constant speed until it stalls.
 

src/pybricks/_common.pyi

@@ -46,13 +46,6 @@ class Control:
     def done(self) -> bool: ...
 
 class Motor(DCMotor):
-    control: Control
-    def __init__(
-        self,
-        port: Port,
-        positive_direction: Direction = Direction.CLOCKWISE,
-        gears: Optional[Union[Collection[int], Collection[Collection[int]]]] = None,
-    ): ...
     def angle(self) -> int: ...
     def speed(self) -> int: ...
     def reset_angle(self, angle: int) -> None: ...