Docstrings updating

.flake8

@@ -1,6 +1,7 @@
 [flake8]
+docstring_style=sphinx
 max-line-length = 127
-ignore = D, Q000, P101, W605, S311,  PLW, PLC, PLR
+ignore = D400, Q000, P101, W605, S311,  PLW, PLC, PLR
 per-file-ignores =
     buildhat/__init__.py:F401
 exclude = docs/conf.py, docs/sphinxcontrib/cmtinc-buildhat.py, docs/sphinx_selective_exclude/*.py

.github/workflows/python-app.yml

@@ -31,6 +31,7 @@ jobs:
         echo "PYTHONPATH=." >> $GITHUB_ENV
     - name: Lint with flake8
       run: |
+        flake8 . --version
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide

buildhat/__init__.py

@@ -1,3 +1,5 @@
+"""Provide all the classes we need for build HAT"""
+
 from .color import ColorSensor
 from .colordistance import ColorDistanceSensor
 from .distance import DistanceSensor

buildhat/color.py

@@ -1,3 +1,5 @@
+"""Color sensor handling functionality"""
+
 import math
 from collections import deque
 from threading import Condition
@@ -11,16 +13,25 @@ class ColorSensor(Device):
     :param port: Port of device
     :raises DeviceError: Occurs if there is no color sensor attached to port
     """
+
     def __init__(self, port):
+        """
+        Initialise color sensor
+
+        :param port: Port of device
+        """
         super().__init__(port)
         self.reverse()
         self.mode(6)
         self.avg_reads = 4
         self._old_color = None
 
     def segment_color(self, r, g, b):
-        """Returns the color name from RGB
+        """Return the color name from RGB
 
+        :param r: Red
+        :param g: Green
+        :param b: Blue
         :return: Name of the color as a string
         :rtype: str
         """
@@ -46,6 +57,9 @@ def rgb_to_hsv(self, r, g, b):
 
         Based on https://www.rapidtables.com/convert/color/rgb-to-hsv.html algorithm
 
+        :param r: Red
+        :param g: Green
+        :param b: Blue
         :return: HSV representation of color
         :rtype: tuple
         """
@@ -69,7 +83,7 @@ def rgb_to_hsv(self, r, g, b):
         return int(h), int(s * 100), int(v * 100)
 
     def get_color(self):
-        """Returns the color
+        """Return the color
 
         :return: Name of the color as a string
         :rtype: str
@@ -78,7 +92,7 @@ def get_color(self):
         return self.segment_color(r, g, b)
 
     def get_ambient_light(self):
-        """Returns the ambient light
+        """Return the ambient light
 
         :return: Ambient light
         :rtype: int
@@ -90,7 +104,7 @@ def get_ambient_light(self):
         return int(sum(readings) / len(readings))
 
     def get_reflected_light(self):
-        """Returns the reflected light
+        """Return the reflected light
 
         :return: Reflected light
         :rtype: int
@@ -115,7 +129,7 @@ def _avgrgbi(self, reads):
         return rgbi
 
     def get_color_rgbi(self):
-        """Returns the color
+        """Return the color
 
         :return: RGBI representation
         :rtype: list
@@ -127,7 +141,7 @@ def get_color_rgbi(self):
         return self._avgrgbi(reads)
 
     def get_color_hsv(self):
-        """Returns the color
+        """Return the color
 
         :return: HSV representation
         :rtype: tuple
@@ -160,7 +174,7 @@ def _cb_handle(self, lst):
                     self._cond.notify()
 
     def wait_until_color(self, color):
-        """Waits until specific color
+        """Wait until specific color
 
         :param color: Color to look for
         """
@@ -175,7 +189,10 @@ def wait_until_color(self, color):
         self.callback(None)
 
     def wait_for_new_color(self):
-        """Waits for new color or returns immediately if first call
+        """Wait for new color or returns immediately if first call
+
+        :return: Name of the color as a string
+        :rtype: str
         """
         self.mode(5)
         if self._old_color is None:
@@ -192,7 +209,5 @@ def wait_for_new_color(self):
         return self._old_color
 
     def on(self):
-        """
-        Turns on the sensor and LED
-        """
+        """Turn on the sensor and LED"""
         self._write("port {} ; plimit 1 ; set -1\r".format(self.port))

buildhat/colordistance.py

@@ -1,3 +1,5 @@
+"""Color distance sensor handling functionality"""
+
 import math
 from collections import deque
 from threading import Condition
@@ -11,16 +13,25 @@ class ColorDistanceSensor(Device):
     :param port: Port of device
     :raises DeviceError: Occurs if there is no colordistance sensor attached to port
     """
+
     def __init__(self, port):
+        """
+        Initialise color distance sensor
+
+        :param port: Port of device
+        """
         super().__init__(port)
         self.on()
         self.mode(6)
         self.avg_reads = 4
         self._old_color = None
 
     def segment_color(self, r, g, b):
-        """Returns the color name from HSV
+        """Return the color name from HSV
 
+        :param r: Red
+        :param g: Green
+        :param b: Blue
         :return: Name of the color as a string
         :rtype: str
         """
@@ -46,6 +57,9 @@ def rgb_to_hsv(self, r, g, b):
 
         Based on https://www.rapidtables.com/convert/color/rgb-to-hsv.html algorithm
 
+        :param r: Red
+        :param g: Green
+        :param b: Blue
         :return: HSV representation of color
         :rtype: tuple
         """
@@ -69,7 +83,7 @@ def rgb_to_hsv(self, r, g, b):
         return int(h), int(s * 100), int(v * 100)
 
     def get_color(self):
-        """Returns the color
+        """Return the color
 
         :return: Name of the color as a string
         :rtype: str
@@ -78,7 +92,7 @@ def get_color(self):
         return self.segment_color(r, g, b)
 
     def get_ambient_light(self):
-        """Returns the ambient light
+        """Return the ambient light
 
         :return: Ambient light
         :rtype: int
@@ -90,7 +104,7 @@ def get_ambient_light(self):
         return int(sum(readings) / len(readings))
 
     def get_reflected_light(self):
-        """Returns the reflected light
+        """Return the reflected light
 
         :return: Reflected light
         :rtype: int
@@ -117,7 +131,7 @@ def _avgrgb(self, reads):
         return rgb
 
     def get_color_rgb(self):
-        """Returns the color
+        """Return the color
 
         :return: RGBI representation
         :rtype: list
@@ -139,7 +153,7 @@ def _cb_handle(self, lst):
                     self._cond.notify()
 
     def wait_until_color(self, color):
-        """Waits until specific color
+        """Wait until specific color
 
         :param color: Color to look for
         """
@@ -154,7 +168,10 @@ def wait_until_color(self, color):
         self.callback(None)
 
     def wait_for_new_color(self):
-        """Waits for new color or returns immediately if first call
+        """Wait for new color or returns immediately if first call
+
+        :return: Name of the color as a string
+        :rtype: str
         """
         self.mode(6)
         if self._old_color is None:
@@ -171,7 +188,5 @@ def wait_for_new_color(self):
         return self._old_color
 
     def on(self):
-        """
-        Turns on the sensor and LED
-        """
+        """Turn on the sensor and LED"""
         self._write("port {} ; plimit 1 ; set -1\r".format(self.port))