Merge pull request #3 from Sensirion/fix-documentation

Update documentation

README.md

@@ -12,7 +12,7 @@ For both scenarios an example is available in the example subfolder of this repo
 
 **Note**: Using the cable as USB to I2c bridge will not allow to achieve the same throughput as with the embedded API.
 
-The API of the driver is described on the [documentation page](https://potential-bassoon-5myg4n3.pages.github.io/) of this repository
+The API of the driver is described on the [documentation page](https://sensirion.github.io/python-uart-scc1) of this repository
 
 ## Getting started
 

docs/api.rst

@@ -4,10 +4,14 @@ API Documentation
 Protocols:
 ----------
 
-.. automodule:: sensirion_uart_scc1.protocols
+.. automodule:: sensirion_uart_scc1.protocols.i2c_transceiver
    :members:
    :undoc-members:
-   :exclude-members: __init__
+
+.. automodule:: sensirion_uart_scc1.protocols.shdlc_transceiver
+   :members:
+   :undoc-members:
+
 
 Exceptions:
 -----------
@@ -24,8 +28,7 @@ Scc1ShdlcDevice:
 
 Drivers:
 --------
-.. automodule:: sensirion_uart_scc1.drivers
+.. automodule:: sensirion_uart_scc1.drivers.scc1_slf3x
    :members:
    :undoc-members:
-   :exclude-members: __init__
 

docs/index.rst

@@ -1,8 +1,8 @@
 Welcome to sensirion_uart_scc1's documentation!
-====================================================
+===============================================
 
 This package contains the driver for the
-[Sensirion SCC1-USB cable](https://www.sensirion.com/products/catalog/SCC1-USB/).
+`Sensirion SCC1-USB cable <https://www.sensirion.com/products/catalog/SCC1-USB/>`_.
 
 
 .. toctree::

sensirion_uart_scc1/drivers/scc1_slf3x.py

@@ -17,10 +17,16 @@ class Scc1Slf3x:
     The Scc1 provides features to support the Slf3x liquid flow sensors. This driver accesses the sensor through the
     API specified by scc1.
     """
-    SENSOR_TYPE = 3  #: Slf3x
+    SENSOR_TYPE = 3  #: Sensor type for Slf3x
     START_MEASUREMENT_DELAY_S = 0.015
 
     def __init__(self, device: Scc1ShdlcDevice, liquid_mode: SlfMode = SlfMode.LIQUI_1) -> None:
+        """
+        Initialize object instance.
+
+        :param device: The Scc1 device that provides the access to the sensor.
+        :param liquid_mode: The liquid that is measured.
+        """
         self._scc1 = device
         self._liquid_config = SLF_PRODUCT_LIQUI_MAP[SlfProduct.SLF3x]
         self._serial_number, self._product_id = self._get_serial_number_and_product_id()
@@ -32,13 +38,17 @@ def __init__(self, device: Scc1ShdlcDevice, liquid_mode: SlfMode = SlfMode.LIQUI
     @property
     def serial_number(self) -> int:
         """
+        Get the serial number
+
         :return: The serial number as integer
         """
         return self._serial_number
 
     @property
     def product_id(self) -> int:
         """
+        Get the product Id
+
         :return: The product identifier as integer
         """
         return self._product_id
@@ -53,7 +63,8 @@ def liquid_mode(self) -> SlfMode:
     @liquid_mode.setter
     def liquid_mode(self, mode: SlfMode) -> None:
         """
-        Set liquid measurement mode
+        Set liquid measurement mode.
+
         :param mode: One of the liquid measurement modes
         """
         if not isinstance(mode, SlfMode):
@@ -68,12 +79,16 @@ def liquid_mode(self, mode: SlfMode) -> None:
     @property
     def liquid_mode_name(self) -> str:
         """
+        Get the name of the liquid.
+
         :return: Name of current liquid measurement mode
         """
         return self.get_liquid_mode_name(self._liquid_mode)
 
     def get_liquid_mode_name(self, mode: SlfMode) -> str:
         """
+        Get the name of the liquid
+
         :param mode: A liquid mode
         :return: Get name of a specific liquid measurement mode
         """
@@ -83,6 +98,7 @@ def get_liquid_mode_name(self, mode: SlfMode) -> str:
     def sampling_interval_ms(self) -> int:
         """
         Sampling interval for synchronous measurement
+
         :return: Current internal sampling interval
         """
         return self._sampling_interval_ms
@@ -92,12 +108,15 @@ def sampling_interval_ms(self, interval_ms: int):
         """
         Set sampling interval for continuous measurement
         This will not be applied while measurement is running
+
         :param interval_ms: The requested measurement interval in milliseconds
         """
         self._sampling_interval_ms = interval_ms
 
     def get_serial_number(self) -> int:
         """
+        Get the serial number of the device.
+
         :return: The sensor serial number
         """
         return self._serial_number
@@ -106,6 +125,7 @@ def get_flow_unit_and_scale(self, command: Optional[int] = None) -> Optional[Tup
         """
         Get the scale factor, unit and sensor sanity check result of the sensor for the given argument.
         (only available on some SLF3x sensor products)
+
         :param command: The 16-bit command to read flow unit and scale factor for. If no value is supplied
             the actual measurement command is used
         :return: A tuple with (scale_factor, flow_unit), None if command is not supported
@@ -123,6 +143,8 @@ def get_last_measurement(self) -> Optional[Tuple[int, int, int]]:
         """
         Read current measurement and starts internal continuous measurement with configured interval, if not
         already started.
+
+        :return: A tuple with flow, temperature and flag
         """
         data = self._scc1.transceive(0x35, [self.SENSOR_TYPE], 0.01)
         if not data:
@@ -133,6 +155,7 @@ def get_last_measurement(self) -> Optional[Tuple[int, int, int]]:
     def start_continuous_measurement(self, interval_ms=0) -> None:
         """
         Start a continuous measurement with a give interval.
+
         :param interval_ms: Measurement interval in milliseconds.
         """
         if self._is_measuring:
@@ -154,7 +177,8 @@ def stop_continuous_measurement(self) -> None:
     def read_extended_buffer(self) -> Tuple[int, int, List[Tuple[Any, ...]]]:
         """
         Read out measurement buffer
-        :return: A tuple with (bytes_remaining, bytes_los, data)
+
+        :return: A tuple with (bytes_remaining, bytes_lost, data)
         """
         data = self._scc1.transceive(0x36, [self.SENSOR_TYPE], 0.01)
         bytes_lost = int(struct.unpack('>I', data[:4])[0])

sensirion_uart_scc1/protocols/i2c_transceiver.py

@@ -10,27 +10,37 @@ class RxTx(Protocol):
 
     @property
     def tx_data(self) -> Optional[bytes]:
-        """The byte array with the data to be sent"""
+        """
+        The byte array with the data to be sent
+        """
 
     @property
     def rx_length(self) -> Optional[int]:
-        """ Number of bytes to read
+        """
+        Number of bytes to read
         """
 
     @property
     def read_delay(self) -> float:
-        """Time between writing and reading an i2c command."""
+        """
+        Time between writing and reading an i2c command.
+        """
 
     def interpret_response(self, data: Optional[bytes]) -> Optional[Tuple[Any, ...]]:
-        """Split the byte array from the response into the fields of the command."""
+        """Split the byte array from the response into the fields of the command.
+
+        :param data: The byte array that needs to be interpreted.
+        :return: A tuple with the interpreted data.
+        """
 
 
 @runtime_checkable
 class I2cTransceiver(Protocol):
 
     def execute(self, slave_addr: int, rx_tx: RxTx) -> Tuple[Any, ...]:
         """
-        Compatibility method for driver adapters
+        Compatibility method for driver adapters.
+
         :param slave_addr: i2c slave address
         :param rx_tx: Object containing the information to execute the communication with the device
         :return: interpreted results

sensirion_uart_scc1/protocols/shdlc_transceiver.py

@@ -7,7 +7,8 @@
 class ShdlcTransceiver(Protocol):
 
     def transceive(self, command: int, data: Union[bytes, Iterable], timeout: float = -1.0) -> Optional[bytes]:
-        """Wrapper method for legacy shdlc-driver compatibility
+        """Wrapper method for legacy shdlc-driver compatibility.
+
         :param command: The command to send (one byte)
         :param data: byte array of the data to send as arguments to the command
         :param timeout: response timeout in seconds (-1 for using default value)

sensirion_uart_scc1/scc1_shdlc_device.py

@@ -18,7 +18,12 @@ class Scc1ShdlcDevice(ShdlcDevice):
     The Scc1 Shdlc device is used to communicate with various sensor using the Sensirion SCC1 sensor cable.
     """
 
-    def __init__(self, connection: ShdlcConnection, slave_address: int) -> None:
+    def __init__(self, connection: ShdlcConnection, slave_address: int = 0) -> None:
+        """Initialize object instance.
+
+        :param connection: The used ShdlcConnection
+        :param slave_address: The SHDLC slave address that is used by this device.
+        """
         super().__init__(connection, slave_address)
         self._version = self.get_version()
         self._serial_number = self.get_serial_number()
@@ -48,10 +53,11 @@ def sensor_reset(self) -> None:
     def transceive(self, command: int, data: Union[bytes, Iterable], timeout: float = -1.0) -> Optional[bytes]:
         """
         Provides a generic way to send shdlc commands.
-        :param command: The command to send (one byte)
-        :param data: byte array of the data to send as arguments to the command
-        :param timeout: response timeout in seconds (-1 for using default value)
-        :return: The returned data as bytes
+
+        :param command: The command to send (one byte).
+        :param data: Byte array of the data to send as arguments to the command.
+        :param timeout: Response timeout in seconds (-1 for using default value).
+        :return: The returned data as bytes.
         """
         if timeout <= 0.0:
             timeout = 3.0