docs: contrib: Actually document the AutoConsoleConnector

This was missed when the `AutoConsoleConnector` was originally added. Take care of it now. Signed-off-by: Rahix <[email protected]>
Rahix · Jul 14, 2024 · e8f7e60 · e8f7e60
1 parent 6f60750
commit e8f7e60
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 0 deletions.
diff --git a/Documentation/contrib/connector.rst b/Documentation/contrib/connector.rst
@@ -5,12 +5,17 @@
 A module containing various additional connectors for convenience.  These
 are:
 
+- :py:class:`~tbot_contrib.connector.auto.AutoConsoleConnector` - Automatically
+  choose an available terminal emulator to connect to a local console device.
 - :py:class:`~tbot_contrib.connector.conserver.ConserverConnector` - Console using `conserver`_.
 - :py:class:`~tbot_contrib.connector.pyserial.PyserialConnector` - Console on localhost using `pyserial`_.
 
 .. _conserver: https://www.conserver.com/
 .. _pyserial: https://github.com/pyserial/pyserial
 
+.. autoclass:: tbot_contrib.connector.auto.AutoConsoleConnector
+   :members: serial_port, baudrate, tools
+
 .. autoclass:: tbot_contrib.connector.conserver.ConserverConnector
    :members: conserver_device, conserver_master, conserver_command, conserver_forcerw
 

diff --git a/tbot_contrib/connector/auto.py b/tbot_contrib/connector/auto.py
@@ -65,6 +65,24 @@ def connect(cls, opt: TeOptions) -> Iterator[channel.Channel]:
 
 
 class AutoConsoleConnector(connector.ConsoleConnector):
+    """
+    Console connector that automatically chooses an available terminal emulator
+    to connect to a local console device.
+
+    **Example**:
+
+    .. code-block:: python
+
+        from tbot_contrib.connector.auto import AutoConsoleConnector
+        from tbot.machine import board
+
+        class FooBoard(AutoConsoleConnector, board.Board):
+            serial_port = "/dev/ttyUSB0"
+            baudrate = 115200
+
+    .. versionadded:: 0.10.3
+    """
+
     @property
     @abc.abstractmethod
     def serial_port(self) -> Union[str, linux.Path]:
@@ -79,6 +97,9 @@ def serial_port(self) -> Union[str, linux.Path]:
     tools = [Tio, Picocom]
     """
     List of terminal emulators which may be used to connect.
+
+    It is best the leave this list complete so tbot can automatically figure
+    out which tool is available and use that one.
     """
 
     @contextlib.contextmanager