From 73981075709f0ac39236c59069458a2bd6d6253a Mon Sep 17 00:00:00 2001
From: Fabio Manganiello <blacklight86@gmail.com>
Date: Tue, 26 Jun 2018 00:36:01 +0200
Subject: [PATCH] Completed documentation for backends

---
 docs/source/backends.rst                      |  5 ++++
 .../platypush/backend/sensor.ir.zeroborg.rst  |  6 +++++
 docs/source/platypush/backend/sensor.leap.rst |  7 ++++++
 .../platypush/backend/sensor.mcp3008.rst      |  8 ++++++
 docs/source/platypush/backend/sensor.rst      |  1 -
 .../platypush/backend/sensor.serial.rst       |  6 +++++
 .../platypush/backend/weather.forecast.rst    |  6 +++++
 .../backend/sensor/ir/zeroborg/__init__.py    | 18 ++++++++++---
 platypush/backend/sensor/leap.py              | 25 +++++++++++++++++++
 platypush/backend/sensor/mcp3008.py           | 11 ++++++++
 platypush/backend/sensor/serial.py            | 10 ++++++++
 platypush/backend/weather/forecast.py         | 12 +++++++++
 platypush/plugins/camera/pi.py                |  2 +-
 13 files changed, 111 insertions(+), 6 deletions(-)
 create mode 100644 docs/source/platypush/backend/sensor.ir.zeroborg.rst
 create mode 100644 docs/source/platypush/backend/sensor.leap.rst
 create mode 100644 docs/source/platypush/backend/sensor.mcp3008.rst
 create mode 100644 docs/source/platypush/backend/sensor.serial.rst
 create mode 100644 docs/source/platypush/backend/weather.forecast.rst

diff --git a/docs/source/backends.rst b/docs/source/backends.rst
index 9beee03fb..f2fb8251a 100644
--- a/docs/source/backends.rst
+++ b/docs/source/backends.rst
@@ -22,4 +22,9 @@ Backends
     platypush/backend/redis.rst
     platypush/backend/scard.rst
     platypush/backend/sensor.rst
+    platypush/backend/sensor.ir.zeroborg.rst
+    platypush/backend/sensor.leap.rst
+    platypush/backend/sensor.mcp3008.rst
+    platypush/backend/sensor.serial.rst
+    platypush/backend/weather.forecast.rst
 
diff --git a/docs/source/platypush/backend/sensor.ir.zeroborg.rst b/docs/source/platypush/backend/sensor.ir.zeroborg.rst
new file mode 100644
index 000000000..169a0f347
--- /dev/null
+++ b/docs/source/platypush/backend/sensor.ir.zeroborg.rst
@@ -0,0 +1,6 @@
+``platypush.backend.sensor.ir.zeroborg``
+========================================
+
+.. automodule:: platypush.backend.sensor.ir.zeroborg
+    :members:
+
diff --git a/docs/source/platypush/backend/sensor.leap.rst b/docs/source/platypush/backend/sensor.leap.rst
new file mode 100644
index 000000000..f2337dc31
--- /dev/null
+++ b/docs/source/platypush/backend/sensor.leap.rst
@@ -0,0 +1,7 @@
+``platypush.backend.sensor.leap``
+=================================
+
+.. automodule:: platypush.backend.sensor.leap
+    :members:
+
+
diff --git a/docs/source/platypush/backend/sensor.mcp3008.rst b/docs/source/platypush/backend/sensor.mcp3008.rst
new file mode 100644
index 000000000..266d573b0
--- /dev/null
+++ b/docs/source/platypush/backend/sensor.mcp3008.rst
@@ -0,0 +1,8 @@
+``platypush.backend.sensor.mcp3008``
+====================================
+
+.. automodule:: platypush.backend.sensor.mcp3008
+    :members:
+
+
+
diff --git a/docs/source/platypush/backend/sensor.rst b/docs/source/platypush/backend/sensor.rst
index b826b9329..6bb68407d 100644
--- a/docs/source/platypush/backend/sensor.rst
+++ b/docs/source/platypush/backend/sensor.rst
@@ -4,4 +4,3 @@
 .. automodule:: platypush.backend.sensor
     :members:
 
-
diff --git a/docs/source/platypush/backend/sensor.serial.rst b/docs/source/platypush/backend/sensor.serial.rst
new file mode 100644
index 000000000..414f5d34e
--- /dev/null
+++ b/docs/source/platypush/backend/sensor.serial.rst
@@ -0,0 +1,6 @@
+``platypush.backend.sensor.serial``
+===================================
+
+.. automodule:: platypush.backend.sensor.serial
+    :members:
+
diff --git a/docs/source/platypush/backend/weather.forecast.rst b/docs/source/platypush/backend/weather.forecast.rst
new file mode 100644
index 000000000..1731a1a39
--- /dev/null
+++ b/docs/source/platypush/backend/weather.forecast.rst
@@ -0,0 +1,6 @@
+``platypush.backend.weather.forecast``
+======================================
+
+.. automodule:: platypush.backend.weather.forecast
+    :members:
+
diff --git a/platypush/backend/sensor/ir/zeroborg/__init__.py b/platypush/backend/sensor/ir/zeroborg/__init__.py
index c9e8c44a3..a26af8b81 100644
--- a/platypush/backend/sensor/ir/zeroborg/__init__.py
+++ b/platypush/backend/sensor/ir/zeroborg/__init__.py
@@ -7,6 +7,20 @@ from platypush.message.event.sensor.ir import IrKeyUpEvent, IrKeyDownEvent
 
 
 class SensorIrZeroborgBackend(Backend):
+    """
+    This backend will read for events on the infrared sensor of a ZeroBorg
+    (https://www.piborg.org/motor-control-1135/zeroborg) circuitry for
+    Raspberry Pi. You can see the codes associated to an IR event from any
+    remote by running the scan utility::
+
+        python -m platypush.backend.sensor.ir.zeroborg.scan
+
+    Triggers:
+
+        * :class:`platypush.message.event.sensor.ir.IrKeyDownEvent` when a key is pressed
+        * :class:`platypush.message.event.sensor.ir.IrKeyUpEvent` when a key is released
+    """
+
     last_message =None
     last_message_timestamp = None
 
@@ -18,10 +32,6 @@ class SensorIrZeroborgBackend(Backend):
         self.logger.info('Initialized Zeroborg infrared sensor backend')
 
 
-    def send_message(self, message):
-        pass
-
-
     def run(self):
         super().run()
 
diff --git a/platypush/backend/sensor/leap.py b/platypush/backend/sensor/leap.py
index 1a04981e7..8caed2b5b 100644
--- a/platypush/backend/sensor/leap.py
+++ b/platypush/backend/sensor/leap.py
@@ -20,6 +20,14 @@ class SensorLeapBackend(Backend):
     Also, you'll need the Leap driver and utils installed on your OS (follow
     instructions at https://www.leapmotion.com/setup/) and the `leapd` daemon
     running to recognize your controller.
+
+    Triggers:
+
+        * :class:`platypush.message.event.sensor.leap.LeapFrameEvent` when a new frame is received
+        * :class:`platypush.message.event.sensor.leap.LeapFrameStartEvent` when a new sequence of frame starts
+        * :class:`platypush.message.event.sensor.leap.LeapFrameStopEvent` when a sequence of frame stops
+        * :class:`platypush.message.event.sensor.leap.LeapConnectEvent` when a Leap Motion device is connected
+        * :class:`platypush.message.event.sensor.leap.LeapDisconnectEvent` when a Leap Motion device disconnects
     """
 
     def __init__(self,
@@ -30,6 +38,23 @@ class SensorLeapBackend(Backend):
                  ],
                  position_tolerance=0.0,  # Position variation tolerance in %
                  *args, **kwargs):
+        """
+        :param position_ranges: It specifies how wide the hand space (x, y and z axes) should be in millimiters.
+
+        Default::
+
+            [
+                [-300.0, 300.0],  # x axis
+                [25.0, 600.0],    # y axis
+                [-300.0, 300.0],  # z axis
+            ]
+
+        :type position_ranges: list[list[float]]
+
+        :param position_tolerance: % of change between a frame and the next to really consider the next frame as a new one (default: 0)
+        :type position_tolerance: float
+        """
+
         super().__init__(*args, **kwargs)
 
         self.position_ranges = position_ranges
diff --git a/platypush/backend/sensor/mcp3008.py b/platypush/backend/sensor/mcp3008.py
index 0a06bc152..b6e2144ed 100644
--- a/platypush/backend/sensor/mcp3008.py
+++ b/platypush/backend/sensor/mcp3008.py
@@ -3,7 +3,18 @@ from platypush.context import get_plugin
 
 
 class SensorMcp3008Backend(SensorBackend):
+    """
+    Backend to poll analog sensor values from an MCP3008 chipset
+    (https://learn.adafruit.com/raspberry-pi-analog-to-digital-converters/mcp3008)
+
+    Requires:
+
+        * ``adafruit-mcp3008`` (``pip install adafruit-mcp3008``)
+        * The :mod:`platypush.plugins.gpio.sensor.mcp3008` plugin configured
+    """
+
     def get_measurement(self):
+        """ get_measurement implementation """
         plugin = get_plugin('gpio.sensor.mcp3008')
         return plugin.get_data().output
 
diff --git a/platypush/backend/sensor/serial.py b/platypush/backend/sensor/serial.py
index cda03f1ae..0c3e7976c 100644
--- a/platypush/backend/sensor/serial.py
+++ b/platypush/backend/sensor/serial.py
@@ -3,7 +3,17 @@ from platypush.context import get_plugin
 
 
 class SensorSerialBackend(SensorBackend):
+    """
+    This backend listens for new events from sensors connected through a serial
+    interface (like Arduino) acting as a wrapper for the ``serial`` plugin.
+
+    Requires:
+
+        * The :mod:`platypush.plugins.serial` plugin configured
+    """
+
     def get_measurement(self):
+        """ Implemnetation of ``get_measurement`` """
         plugin = get_plugin('serial')
         return plugin.get_data().output
 
diff --git a/platypush/backend/weather/forecast.py b/platypush/backend/weather/forecast.py
index 7d0867a85..f89faadb7 100644
--- a/platypush/backend/weather/forecast.py
+++ b/platypush/backend/weather/forecast.py
@@ -7,6 +7,18 @@ from platypush.message.event.weather import NewWeatherConditionEvent
 
 
 class WeatherForecastBackend(Backend):
+    """
+    Weather forecast backend - listens and propagates new weather events.
+
+    Triggers:
+
+        * :class:`platypush.message.event.weather.NewWeatherConditionEvent` when there is a weather condition update
+
+    Requires:
+
+        * The :mod:`platypush.plugins.weather.forecast` plugin configured
+    """
+
     def __init__(self, poll_seconds, **kwargs):
         super().__init__(**kwargs)
         self.poll_seconds = poll_seconds
diff --git a/platypush/plugins/camera/pi.py b/platypush/plugins/camera/pi.py
index 7ed993d6b..09cdab45a 100644
--- a/platypush/plugins/camera/pi.py
+++ b/platypush/plugins/camera/pi.py
@@ -11,7 +11,7 @@ from platypush.plugins import Plugin
 class CameraPiPlugin(Plugin):
     """
     Plugin to control a Pi camera.
-    It acts as a wrapper around the :ref:`platypush.backend.camera.pi` backend
+    It acts as a wrapper around the :mod:`platypush.backend.camera.pi` backend
     to programmatically control the status.
     """