Update docs

.flake8

@@ -5,7 +5,7 @@ max-line-length = 88
 # F401: Module imported but unused.
 # D100-D107: Missing docstrings
 # D200: One-line docstring should fit on one line with quotes.
-extend-ignore = E203,E402,E501,F401,D100,D101,D102,D103,D104,D105,D106,D107,D200
+extend-ignore = E203,E402,E501,F401,D100,D101,D102,D103,D104,D105,D106,D107,D200,D401
 docstring-convention = numpy
 # Ignore missing docstrings within unit testing functions.
 per-file-ignores = **/tests/:D100,D101,D102,D103,D104,D105,D106,D107

README.rst

@@ -10,7 +10,7 @@ Belay
 
 Belay is a library that enables the rapid development of projects that interact with hardware via a micropython-compatible board.
 
-Belay works by automatically using the REPL interface of a micropython board from Python code running on PC.
+Belay works by interacting with the REPL interface of a micropython board from Python code running on PC.
 
 `Quick Video of Belay in 22 seconds.`_
 

belay/device.py

@@ -91,7 +91,7 @@ def local_hash_file(fn):
     return binascii.hexlify(hasher.digest()).decode()
 
 
-class Executer(ABC):
+class _Executer(ABC):
     def __init__(self, device):
         # To avoid Executer.__setattr__ raising an error
         object.__setattr__(self, "_belay_device", device)
@@ -112,15 +112,15 @@ def __call__(self):
         raise NotImplementedError
 
 
-class TaskExecuter(Executer):
+class _TaskExecuter(_Executer):
     def __call__(
         self,
         f: Optional[Callable[..., JsonSerializeable]] = None,
         /,
         minify: bool = True,
         register: bool = True,
     ) -> Callable[..., JsonSerializeable]:
-        """Send code to device that executes when decorated function is called on-host.
+        """Decorator that send code to device that executes when decorated function is called on-host.
 
         Parameters
         ----------
@@ -180,22 +180,23 @@ def multi_executer(*args, **kwargs):
         return multi_executer
 
 
-class ThreadExecuter(Executer):
+class _ThreadExecuter(_Executer):
     def __call__(
         self,
         f: Optional[Callable[..., None]] = None,
         /,
         minify: bool = True,
         register: bool = True,
     ) -> Callable[..., None]:
-        """Send code to device that spawns a thread when executed.
+        """Decorator that send code to device that spawns a thread when executed.
 
         Parameters
         ----------
         f: Callable
             Function to decorate.
         minify: bool
             Minify ``cmd`` code prior to sending.
+            Defaults to ``True``.
         register: bool
             Assign an attribute to ``self`` with same name as ``f``.
             Defaults to ``True``.
@@ -260,8 +261,8 @@ def __init__(
         self._board = Pyboard(*args, **kwargs)
         self._board.enter_raw_repl()
 
-        self.task = TaskExecuter(self)
-        self.thread = ThreadExecuter(self)
+        self.task = _TaskExecuter(self)
+        self.thread = _ThreadExecuter(self)
 
         self(_BELAY_STARTUP_CODE)
         if startup:

docs/source/Quick Start.rst

@@ -48,6 +48,11 @@ Invoking ``bar = foo(5)`` on host sends a command to the device to execute the f
 The result, ``10``, is sent back to the host and results in ``bar == 10``.
 This is the preferable way to interact with hardware.
 
+If a task is registered to multiple Belay devices, it will execute sequentially on the devices in the order that they were decorated (bottom upwards).
+The return value would be a list of results in order.
+
+To explicitly call a task on just one device, it can be invoked ``device.task.foo()``.
+
 thread
 ^^^^^^
 
@@ -68,6 +73,10 @@ thread
 Not all MicroPython boards support threading, and those that do typically have a maximum of ``1`` thread.
 The decorated function has no return value.
 
+If a thread is registered to multiple Belay devices, it will execute sequentially on the devices in the order that they were decorated (bottom upwards).
+
+To explicitly call a thread on just one device, it can be invoked ``device.thread.led_loop()``.
+
 sync
 ^^^^
 For more complicated hardware interactions, additional python modules/files need to be available on the device's filesystem.

docs/source/api.rst

@@ -1,7 +1,29 @@
 API
 ===
 
+.. autoclass:: belay.Device
+   :members:
+
+   .. method:: task(f: Optional[Callable[..., None]] = None, /, minify: bool = True, register: bool = True)
+
+      Decorator that send code to device that executes when decorated function is called on-host.
+
+      :param Callable f: Function to decorate.
+      :param bool minify: Minify ``cmd`` code prior to sending. Defaults to ``True``.
+      :param bool register: Assign an attribute to ``self.task`` with same name as ``f``. Defaults to ``True``.
+
+   .. method:: thread(f: Optional[Callable[..., None]] = None, /, minify: bool = True, register: bool = True)
+
+      Decorator that send code to device that spawns a thread when executed.
+
+      :param Callable f: Function to decorate.
+      :param bool minify: Minify ``cmd`` code prior to sending. Defaults to ``True``.
+      :param bool register: Assign an attribute to ``self.thread`` with same name as ``f``. Defaults to ``True``.
+
+
+
 .. automodule:: belay
    :members:
    :undoc-members:
    :show-inheritance:
+   :exclude-members: Device

docs/source/conf.py

@@ -47,6 +47,7 @@
 exclude_patterns = []
 
 smartquotes = False
+add_module_names = False
 
 # Napoleon settings
 napoleon_google_docstring = True

examples/08_multiple_devices/README.rst

@@ -3,4 +3,7 @@ Example 08: Multiple Devices
 
 Belay can interact with multiple micropython boards on different ports.
 Tasks and Threads can be decorated multiple times from different devices.
-When executed, devices are executed in the order that they were decorated (bottom upwards).
+When invoked, the resulting decorated function will execute on the devices in the order that they were decorated (bottom upwards).
+
+To execute a task on just one specific device, it can be accessed like ``device1.task.set_led``.
+Similarly, to execute a thread on just one specific device, call ``device1.thread.blink_loop``.