Merge pull request #266 from jumpstarter-dev/doctest-more

Hide __init__ signature from autogenerated client classes, expand doctest coverage

Author: mangelajo

docs/source/api-reference/drivers/can.md

@@ -3,11 +3,11 @@
 The CAN driver is a driver for using CAN bus connections.
 
 ```{eval-rst}
-.. autoclass:: jumpstarter_driver_can.client.CanClient
+.. autoclass:: jumpstarter_driver_can.client.CanClient()
     :members:
 ```
 
 ```{eval-rst}
-.. autoclass:: jumpstarter_driver_can.client.IsoTpClient
+.. autoclass:: jumpstarter_driver_can.client.IsoTpClient()
     :members:
-```
+```

docs/source/api-reference/drivers/pyserial.md

@@ -24,7 +24,7 @@ export:
 
 ## PySerialClient API
 ```{eval-rst}
-.. autoclass:: jumpstarter_driver_pyserial.client.PySerialClient
+.. autoclass:: jumpstarter_driver_pyserial.client.PySerialClient()
     :members: pexpect, open, stream, open_stream, close
 ```
 

docs/source/api-reference/drivers/sdwire.md

@@ -4,10 +4,27 @@ The SDWire driver is an storgate multiplexer driver for using the SDWire
 multiplexer. This device multiplexes an SD card between the DUT and the
 exporter host.
 
+## Driver Configuration
+
+```{literalinclude} sdwire.yaml
+:language: yaml
+```
+
+```{doctest}
+:hide:
+>>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance
+>>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/sdwire.yaml").instantiate()
+Traceback (most recent call last):
+...
+FileNotFoundError: failed to find sd-wire device
+```
+
+## Client API
+
 The SDWire driver implements the `StorageMuxClient` class, which is a generic
 storage class.
 
 ```{eval-rst}
-.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClient
+.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClient()
     :members:
 ```

docs/source/api-reference/drivers/sdwire.yaml

@@ -0,0 +1,8 @@
+type: "jumpstarter_driver_sdwire.driver.SDWire"
+config:
+  # optional serial number of the sd-wire device
+  # the first one found would be used if unset
+  serial: "sdw-00001"
+  # optional path to the block device exposed by sd-wire
+  # automatically detected if unset
+  storage_device: "/dev/disk/by-diskseq/1"

docs/source/api-reference/drivers/ustreamer.md

@@ -4,7 +4,24 @@ The Ustreamer driver is a driver for using the ustreamer video streaming server
 driven by the jumpstarter exporter. This driver takes a video device and
 exposes both snapshot and streaming interfaces.
 
+## Driver configuration
+
+```{literalinclude} ustreamer.yaml
+:language: yaml
+```
+
+```{doctest}
+:hide:
+>>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance
+>>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/ustreamer.yaml").instantiate()
+Traceback (most recent call last):
+...
+io.UnsupportedOperation: fileno
+```
+
+## Client API
+
 ```{eval-rst}
-.. autoclass:: jumpstarter_driver_ustreamer.client.UStreamerClient
+.. autoclass:: jumpstarter_driver_ustreamer.client.UStreamerClient()
     :members:
 ```

docs/source/api-reference/drivers/ustreamer.yaml

@@ -0,0 +1,8 @@
+type: "jumpstarter_driver_ustreamer.driver.UStreamer"
+config:
+  # name or path of the ustreamer executable
+  # defaults to finding ustreamer from path
+  executable: "ustreamer"
+  args: # extra arguments to pass to ustreamer
+    brightness: auto # --brightness=auto
+    contrast: default # --contract=default

docs/source/api-reference/drivers/yepkit.md

@@ -36,7 +36,7 @@ export:
 The yepkit ykush driver provides a `PowerClient` with the following API:
 
 ```{eval-rst}
-.. autoclass:: jumpstarter_driver_power.client.PowerClient
+.. autoclass:: jumpstarter_driver_power.client.PowerClient()
     :members: on, off
 ```
 

packages/jumpstarter/jumpstarter/config/exporter.py

@@ -29,6 +29,10 @@ def instantiate(self) -> Driver:
 
         return driver_class(children=children, **self.config)
 
+    @classmethod
+    def from_path(cls, path: str) -> ExporterConfigV1Alpha1DriverInstance:
+        with open(path) as f:
+            return cls.model_validate(yaml.safe_load(f))
 
 class ExporterConfigV1Alpha1(BaseModel):
     BASE_PATH: ClassVar[Path] = Path("/etc/jumpstarter/exporters")