Address doc gen errors

Author: jmattsson

docs/Makefile

@@ -8,7 +8,10 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile clean
 
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	-rm -rf "$(BUILDDIR)" "$(SOURCEDIR)/submodules"

docs/source/.gitignore

@@ -0,0 +1 @@
+submodules

docs/source/api.rst

@@ -13,5 +13,7 @@ __________
    :toctree: submodules
    :recursive:
 
-    devices
-    listener
+   devices
+   plug_api
+   virtual_household
+   xlatemsg

src/powersensor_local/__init__.py

@@ -22,12 +22,12 @@
 a household view is available in VirtualHousehold.
 
 Quick overview:
-• PlugApi is the recommended API layer
-• PlugListenerUdp is the UDP lower-level abstraction used by PlugApi
-• PlugListenerTcp is the TCP lower-level abstraction used by PlugApi
-• PowersensorDevices is the legacy main API layer
-• LegacyDiscovery provides access to the legacy discovery mechanism
-• VirtualHousehold can be used to translate events into a household view
+  - PlugApi is the recommended API layer
+  - PlugListenerUdp is the UDP lower-level abstraction used by PlugApi
+  - PlugListenerTcp is the TCP lower-level abstraction used by PlugApi
+  - PowersensorDevices is the legacy main API layer
+  - LegacyDiscovery provides access to the legacy discovery mechanism
+  - VirtualHousehold can be used to translate events into a household view
 
 The 'plugevents' and 'rawplug' modules are helper utilities provided as
 debug aids, which get installed under the names ps-plugevents and ps-rawplug

src/powersensor_local/devices.py

@@ -33,18 +33,18 @@ async def start(self, async_event_cb):
         of the local network to discover present devices. The callback is
         of the form
 
-        async def yourcallback(event: dict)
+          async def yourcallback(event: dict) -> None
 
         Known events:
 
-        scan_complete:
+        **scan_complete**
             Indicates the discovery of Powersensor devices has completed.
             Emitted in response to start() and rescan() calls.
             The number of found gateways (plugs) is reported.
 
             { event: "scan_complete", gateway_count: N }
 
-        device_found:
+        **device_found**
             A new device found on the network.
             The order found devices are announced is not fixed.
 
@@ -53,16 +53,14 @@ async def yourcallback(event: dict)
               mac: "...",
             }
 
-        device_lost:
+        **device_lost**
             A device appears to no longer be present on the network.
 
             { event: "device_lost", mac: "..." }
 
-
         Additionally, all events described in xlatemsg.translate_raw_message
         may be issued. The event name is inserted into the field 'event'.
 
-
         The start function returns the number of found gateway plugs.
         Powersensor devices aren't found directly as they are typically not
         on the network, but are instead detected when they relay data through

src/powersensor_local/plug_listener_tcp.py

@@ -1,4 +1,4 @@
-"""An interface for accessing the event stream from a Powersensor plug."""
+"""Internal helper for accessing the event stream from a Powersensor plug."""
 import asyncio
 import json
 
@@ -12,18 +12,19 @@
 from powersensor_local.async_event_emitter import AsyncEventEmitter
 
 class PlugListenerTcp(AsyncEventEmitter):
-    """An interface class for accessing the event stream from a single plug.
+    """Internal helper for accessing the event stream from a Powersensor plug.
+
     The following events may be emitted:
       - ("connecting")   Whenever a connection attempt is made.
       - ("connected")    When a connection is successful.
       - ("disconnected") When a connection is dropped, be it intentional or not.
       - ("message",{...}) For each event message received from the plug. The
-      plug's JSON message is decoded into a dict which is passed as the second
-      argument to the registered event handler(s).
+        plug's JSON message is decoded into a dict which is passed as the second
+        argument to the registered event handler(s).
       - ("malformed",line) If JSON decoding of a message fails. The raw line
-      is included (as a byte string).
+        is included (as a byte string).
 
-      The event handlers must be async.
+    The event handlers must be async.
     """
 
     def __init__(self, ip, port=49476):

src/powersensor_local/plug_listener_udp.py

@@ -1,4 +1,4 @@
-"""An interface for accessing the event stream from a Powersensor plug."""
+"""Internal helper for accessing the event stream from a Powersensor plug."""
 import asyncio
 import json
 import socket
@@ -15,18 +15,19 @@
 # pylint: disable=R0902
 # @todo: dream up a base class for PlugListener that TCP/UDP subclass
 class PlugListenerUdp(AsyncEventEmitter, asyncio.DatagramProtocol):
-    """An interface class for accessing the event stream from a single plug.
+    """Internal helper for accessing the event stream from a Powersensor plug.
+
     The following events may be emitted:
       - ("connecting")   Whenever a connection attempt is made.
       - ("connected")    When a connection is successful.
       - ("disconnected") When a connection is dropped, be it intentional or not.
       - ("message",{...}) For each event message received from the plug. The
-      plug's JSON message is decoded into a dict which is passed as the second
-      argument to the registered event handler(s).
+        plug's JSON message is decoded into a dict which is passed as the
+        second argument to the registered event handler(s).
       - ("malformed",line) If JSON decoding of a message fails. The raw line
-      is included (as a byte string).
+        is included (as a byte string).
 
-      The event handlers must be async.
+    The event handlers must be async.
     """
 
     def __init__(self, ip, port=49476):

src/powersensor_local/xlatemsg.py

@@ -128,21 +128,24 @@ def translate_raw_message(message: dict, relay_mac: str):
     Translates raw messages from the plug API into stable, documented events.
 
     Args:
-      - message: The raw message (decoded into a dict)
-      - relay_mac: The id (MAC address) of the plug the message was received
+      message: The raw message (decoded into a dict)
+      relay_mac: The id (MAC address) of the plug the message was received
         through. When the message origin is not the plug, the events returned
         from this function will have "via": relay_mac added to denote what
         plug is acting as the relay for them.
 
     Returns:
+
       A dictionary of events, quite possibly empty. The key is the event
       name that the event should be emitted under, with the value being
       the event data itself (a dict).
 
     Possible events returned:
+
       - "average_power": An event denoting the average power seen over a
         short duration, such as 1 or 30 seconds typically. Both plugs and
         powersensors may originate these. The event data comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug, if from a sensor.
@@ -155,6 +158,7 @@ def translate_raw_message(message: dict, relay_mac: str):
         information on the power components feeding into the power measurement.
         To be read in conjunction with the "average_power" message with the
         same starttime_utc value. Comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "starttime_utc": Seconds since the Unix Epoch, in UTC.
@@ -165,6 +169,7 @@ def translate_raw_message(message: dict, relay_mac: str):
 
       - "summation_energy": An event reporting an energy summation value.
         Issued for both plugs and sensors. Comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug, if from a sensor.
@@ -184,6 +189,7 @@ def translate_raw_message(message: dict, relay_mac: str):
       - "average_flow": An event denoting the average flow rate seen over a
         short duration, such as 1 or 30 seconds typically. Only originated by
         water sensors. The event data comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug.
@@ -193,6 +199,7 @@ def translate_raw_message(message: dict, relay_mac: str):
 
       - "summation_volume": An event reporting a volume summation value.
         Issued only for water sensors. Comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug.
@@ -209,33 +216,36 @@ def translate_raw_message(message: dict, relay_mac: str):
         unknown unit, for an average over a short duration, such as 1 or 30
         seconds typically. Issued by powersensors, prior to calibration.
         The event data comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug.
           - "starttime_utc": Seconds since the Unix Epoch, in UTC.
           - "duration_s": The number of seconds the reading is calculated over.
           - "value": The value, in unspecified units. The only valid thing
-          to use this value for is display it relative to other uncalibrated
-          values from the same device. The magnitude of the value is an
-          indication of the strength of the signal seen by the sensor, but
-          the unit is most definitely NOT in Watts. For most purposes, this
-          event can (and should be) ignored. Once the backend has successfully
-          calibrated the sensor against one or more plugs, these events
-          will be replaced by "average_power" events instead.
+            to use this value for is display it relative to other uncalibrated
+            values from the same device. The magnitude of the value is an
+            indication of the strength of the signal seen by the sensor, but
+            the unit is most definitely NOT in Watts. For most purposes, this
+            event can (and should be) ignored. Once the backend has successfully
+            calibrated the sensor against one or more plugs, these events
+            will be replaced by "average_power" events instead.
 
       - "battery_level": An event reporting the battery level of a sensor.
         The event data comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug.
           - "starttime_utc": Seconds since the Unix Epoch, in UTC.
           - "volts": The current battery level, in Volts. Sensors operate
-          on 3.7V nominally, with a fully charged battery at around 4.2V.
-          Precise battery curves vary individually.
+            on 3.7V nominally, with a fully charged battery at around 4.2V.
+            Precise battery curves vary individually.
 
       - "radio_signal_quality": An event reporting radio signal quality for
         a sensor. Note that this is for the long-range radio comms with the
         plug, not for the WiFi signal. The event comprises:
+
           - "mac": The MAC address of the device.
           - "role": The assigned role of the device, if known.
           - "via": The id of the relaying plug.
@@ -245,7 +255,6 @@ def translate_raw_message(message: dict, relay_mac: str):
             during the reporting window. Values below -90 are considered poor
             reception.
           - "last_rssi": The most recent RSSI value.
-
     """
     evs: dict = {}
     typ = message['type']