etplib v0.2.1

 - Add types for API parameters
 - Fix return values for some APIs
 - Add
    - docstrings for APIs
    - mkdocs config.
    - readthedocs config

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: docs/mkdocs/mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/mkdocs/.gitignore

@@ -0,0 +1 @@
+site/

docs/mkdocs/mkdocs.yml

@@ -0,0 +1,53 @@
+site_name: Embedded Tester Protocol Library
+
+docs_dir: src
+site_url: https://etplib.readthedocs.io/
+repo_url: https://github.com/jabezwinston/etplib-python
+repo_name: etplib-python
+copyright: Copyright © 2024 Jabez Winston
+
+theme:
+  name: readthedocs
+  highlightjs: true
+
+nav:
+  - Introduction: index.md
+  - API reference guide:
+    - General: api/general.md
+    - GPIO: api/gpio.md
+    - ADC: api/adc.md
+    - PWM: api/pwm.md
+    - I2C: api/i2c.md
+    - SPI: api/spi.md
+
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          import:
+            - https://docs.python.org/3/objects.inv
+          paths: [../..]
+          options:
+            docstring_options:
+                ignore_init_summary: true
+            # docstring_section_style: numpy
+            filters: ["!^_"]
+            heading_level: 1
+            inherited_members: true
+            merge_init_into_class: true
+            parameter_headings: true
+            preload_modules: [mkdocstrings]
+            relative_crossrefs: true
+            scoped_crossrefs: true
+            separate_signature: true
+            show_bases: false
+            show_inheritance_diagram: true
+            show_root_heading: true
+            show_root_full_path: false
+            show_signature_annotations: true
+            show_source: false
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            summary: true
+            unwrap_annotated: true

docs/mkdocs/src/api/adc.md

@@ -0,0 +1 @@
+::: etplib.adc.ADC

docs/mkdocs/src/api/general.md

@@ -0,0 +1 @@
+::: etplib.lib.ETP

docs/mkdocs/src/api/gpio.md

@@ -0,0 +1 @@
+::: etplib.gpio.GPIO

docs/mkdocs/src/api/i2c.md

@@ -0,0 +1 @@
+::: etplib.i2c.I2C

docs/mkdocs/src/api/pwm.md

@@ -0,0 +1 @@
+::: etplib.pwm.PWM

docs/mkdocs/src/api/spi.md

@@ -0,0 +1 @@
+::: etplib.spi.SPI

docs/mkdocs/src/index.md

@@ -0,0 +1 @@
+../../../README.md

docs/requirements.in

@@ -0,0 +1,4 @@
+mkdocs
+mkdocstrings[python]
+markdown-include
+black

docs/requirements.txt

@@ -0,0 +1,90 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+black==24.10.0
+    # via -r requirements.in
+click==8.1.7
+    # via
+    #   black
+    #   mkdocs
+    #   mkdocstrings
+colorama==0.4.6
+    # via griffe
+ghp-import==2.1.0
+    # via mkdocs
+griffe==1.5.1
+    # via mkdocstrings-python
+jinja2==3.1.4
+    # via
+    #   mkdocs
+    #   mkdocstrings
+markdown==3.7
+    # via
+    #   markdown-include
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+    #   pymdown-extensions
+markdown-include==0.8.1
+    # via -r requirements.in
+markupsafe==3.0.2
+    # via
+    #   jinja2
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+mkdocs==1.6.1
+    # via
+    #   -r requirements.in
+    #   mkdocs-autorefs
+    #   mkdocstrings
+mkdocs-autorefs==1.2.0
+    # via
+    #   mkdocstrings
+    #   mkdocstrings-python
+mkdocs-get-deps==0.2.0
+    # via mkdocs
+mkdocstrings[python]==0.27.0
+    # via
+    #   -r requirements.in
+    #   mkdocstrings-python
+mkdocstrings-python==1.12.2
+    # via mkdocstrings
+mypy-extensions==1.0.0
+    # via black
+packaging==24.2
+    # via
+    #   black
+    #   mkdocs
+pathspec==0.12.1
+    # via
+    #   black
+    #   mkdocs
+platformdirs==4.3.6
+    # via
+    #   black
+    #   mkdocs-get-deps
+    #   mkdocstrings
+pymdown-extensions==10.12
+    # via mkdocstrings
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pyyaml==6.0.2
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+six==1.17.0
+    # via python-dateutil
+watchdog==6.0.0
+    # via mkdocs

etplib/adc.py

@@ -25,11 +25,23 @@ def __init__(self, etp):
         self.reference_mv = 3300
         self.resolution = 10
 
-    """
-    Query ADC information
-    """
-
-    def get_info(self):
+    def get_info(self) -> dict:
+        """Query ADC information.
+        
+        Returns:
+            dict: Dictionary containing ADC information of the following format:
+
+                | Key           | Value Type | Description                                  |
+                |---------------|------------|----------------------------------------------|
+                | num_adc       | int        | Number of ADCs                               |
+                | num_channels  | int        | Number of channels                           |
+                | resolution    | int        | Resolution of ADC                            |
+                | reference     | int        | Reference voltage of ADC                     |
+                | max_rate      | int        | Maximum sampling rate of ADC                 |
+                | port_count    | int        | Number of ADC ports                          |
+                | ports         | list       | List of ADC ports and their corresponding pins |
+            
+        """
         adc_info_cmd = self.code << 8 | self.ops['info']
         cmd = self.etp.frame_packet(adc_info_cmd)
         self.etp.cmd_queue.put(cmd)
@@ -53,31 +65,45 @@ def get_info(self):
             'ports': adc_info
         }
 
-    """
-    Enable/Disable ADC pins
-
-    """
 
-    def init(self, pin_list):
+    def init(self, pin_list: dict) -> int:
+        """Enable/Disable ADC pins.
+        
+        Args:
+            pin_list: Dictionary of pins to enable/disable.
+        
+        """
         adc_init_cmd = self.code << 8 | self.ops['init']
         adc_pin_mask = 0
         adc_enable_mask = 0
         for pin in pin_list.keys():
             port, pin_num = self.etp.gpio.decode_gpio_pin(pin)
-            if (pin_list[pin] == True):
+            if pin_list[pin] is True:
                 adc_enable_mask |= (1 << pin_num)
             adc_pin_mask |= (1 << pin_num)
 
         cmd = self.etp.frame_packet(adc_init_cmd, struct.pack('<BII', ord(port), adc_pin_mask, adc_enable_mask))
         self.etp.cmd_queue.put(cmd)
-        self.etp.read_rsp()
-
-    """
-    Control the ADC pin
-    
-    """
-
-    def ctrl(self, pin, **kwargs):
+        _, status = self.etp.read_rsp()
+        return status
+
+    def ctrl(self, pin: str, **kwargs) -> int:
+        """
+        Control ADC pin.
+
+        Args:
+            pin: ADC pin to control.
+            **kwargs (dict): Keyword arguments.
+
+        Keyword Args: **kwargs:
+            resolution (int, optional): Resolution of ADC pin. Defaults to self.resolution.
+            reference_mv (int, optional): Reference voltage of ADC pin. Defaults to self.reference_mv.
+            rate (int, optional): Sampling rate of ADC pin. Defaults to 1000.
+            start (int, optional): Start value of ADC pin. Defaults to 0.
+
+        Returns:
+            Status code.
+        """
         adc_ctrl_cmd = self.code << 8 | self.ops['ctrl']
         port, pin = self.etp.gpio.decode_gpio_pin(pin)
 
@@ -109,17 +135,20 @@ def ctrl(self, pin, **kwargs):
 
         cmd = self.etp.frame_packet(adc_ctrl_cmd, struct.pack('<BBBHHBB', ord(port), pin, resolution, reference_mv, rate, unit, start))
         self.etp.cmd_queue.put(cmd)
-        rsp, _ = self.etp.read_rsp()
-        return rsp
-
-    """
-    Read data from ADC pin
-
-    """
-
-    def read(self, pin_str):
+        _, status = self.etp.read_rsp()
+        return status
+
+    def read(self, pin: str) -> int:
+        """Read data from ADC pin.
+        
+        Args:
+            pin: ADC pin to read from.
+
+        Returns:
+            ADC value read from the pin.
+        """
         adc_read_cmd = self.code << 8 | self.ops['read']
-        port, pin = self.etp.gpio.decode_gpio_pin(pin_str)
+        port, pin = self.etp.gpio.decode_gpio_pin(pin)
         cmd = self.etp.frame_packet(adc_read_cmd, struct.pack('<BB', ord(port), pin))
         self.etp.cmd_queue.put(cmd)
         rsp, _ = self.etp.read_rsp()