doc: experimenting with autodoc generation

Observations:

* Type annotations tend to be verbose, for example:

        blink(color1: typing.Union[pblight.Color, pblight.RGB, NoneType], color2: typing.Union[pblight.Color, pblight.RGB, NoneType], pattern: pblight.Pattern) → None

* There seems to be a bug with .. autodata::

README.md

@@ -0,0 +1,6 @@
+Fake Pybricks
+=============
+
+This is a standard Python 3.x library that provides the Pybricks API with a
+totally fake implementation. It is used to provide documentation and type
+hints for code completion.

_pbport.py

@@ -0,0 +1,7 @@
+"""Private base class for ports"""
+
+from enum import Enum
+
+
+class Port(Enum):
+    pass

movehub.py

@@ -0,0 +1,30 @@
+"""This module is for the LEGO BOOST Move Hub."""
+
+import _pbport
+
+from pblight import Light
+from pbsensor import TouchSensor
+
+
+class Port(_pbport.Port):
+    """The ports on the LEGO BOOST Move Hub"""
+    HUB = -1
+    """The Move Hub itself"""
+
+    A = ord('A')
+    """Built-in motor 'A'"""
+
+    B = ord('B')
+    """Built-in motor 'B'"""
+
+    C = ord('C')
+    """I/O port 'C'"""
+
+    D = ord('D')
+    """I/O port 'D'"""
+
+button = TouchSensor(Port.HUB)
+"""The button on the Move Hub"""
+
+light = Light(Port.HUB)
+"""The light on the Move Hub"""

pblight.py

@@ -0,0 +1,108 @@
+"""Lights can be built into programmable bricks or can be plugged into I/O
+ports."""
+
+from collections import namedtuple
+from enum import Enum
+from typing import Union
+
+from _pbport import Port
+
+
+class Color(Enum):
+    """Color names"""
+
+    red = 1
+    """The light will be red"""
+
+    orange = 2
+    """The light will be orange"""
+
+    yellow = 3
+    """The light will be yellow"""
+
+    green = 4
+    """The light will be green"""
+
+    blue = 5
+    """The light will be blue"""
+
+    purple = 6
+    """The light will be purple"""
+
+    white = 7
+    """The light will be white"""
+
+RGB = namedtuple('RGB', 'r g b')
+"""Red, green, blue value"""
+
+
+class Pattern(Enum):
+    """Blink patterns"""
+
+    flash = 1
+    """The light will alternate between *color1* and *color2* once per
+     second"""
+
+    fade = 2
+    """The light will fade gradually from *color1* to *color2* and back once
+     per second"""
+
+
+class Light():
+    """Class representing a light"""
+    def __init__(self, port: Port):
+        """Creates a new instance
+
+        Args:
+            port: the port the light is connected to
+        """
+        self._port = port
+
+    def on(self, color: Union[Color, RGB, None]) -> None:
+        """Turns the light on with the specified color
+
+        Args:
+            color: the color
+        """
+        pass
+
+    def off(self) -> None:
+        pass
+
+    def blink(self, color1: Union[Color, RGB, None],
+              color2: Union[Color, RGB, None], pattern: Pattern) -> None:
+        """Blinks the light using the specified pattern
+
+        Args:
+            color1: the first color in the pattern
+            color2: the second color in the pattern
+            pattern: the pattern
+        """
+        pass
+
+    @property
+    def has_red(self) -> bool:
+        """Checks if the light can be red
+
+        Returns:
+            ``True`` if the light can be red
+        """
+        return False
+
+    @property
+    def has_green(self) -> bool:
+        """Checks if the light can be green
+
+        Returns:
+            ``True`` if the light can be green
+        """
+        return False
+
+    @property
+    def has_blue(self) -> bool:
+        """Checks if the light can be blue
+
+        Returns:
+            ``True`` if the light can be blue
+        """
+        return False

pbsensor.py

@@ -0,0 +1,24 @@
+"""Sensors are input devices."""
+
+from _pbport import Port
+
+
+class TouchSensor():
+    """Represents a touch sensor with two states, pressed and released"""
+    def __init__(self, port: Port):
+        """Creates a new instance
+
+        Raises:
+            ValueError: The *port* is not a valid port
+            RuntimeError: There is not a touch sensor connected to this port
+        """
+        self._port = port
+
+    @property
+    def is_pressed(self) -> bool:
+        """Checks if the touch sensor is pressed.
+
+        Returns:
+            ``True`` if the sensor is pressed, otherwise ``False``
+        """
+        return False