Misc documentation improvements.

docs/source/conf.py

@@ -15,17 +15,14 @@ import sys
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath("./_ext"))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'Platypush'
-copyright = '2017-2021, Fabio Manganiello'
+copyright = '2017-2023, Fabio Manganiello'
-author = 'Fabio Manganiello'
+author = 'Fabio Manganiello <fabio@manganiello.tech>'
 
 # The short X.Y version
 version = ''

platypush/plugins/bluetooth/__init__.py

@@ -41,8 +41,8 @@ class BluetoothPlugin(RunnablePlugin, EnumSwitchEntityManager):
     """
     Plugin to interact with Bluetooth devices.
 
-    This plugin uses `_Bleak_ <https://github.com/hbldh/bleak>`_ to interact
+    This plugin uses `Bleak <https://github.com/hbldh/bleak>`_ to interact
-    with the Bluetooth stack and `_Theengs_ <https://github.com/theengs/decoder>`_
+    with the Bluetooth stack and `Theengs <https://github.com/theengs/decoder>`_
     to map the services exposed by the devices into native entities.
 
     The full list of devices natively supported can be found

platypush/plugins/camera/pi/__init__.py

@@ -13,8 +13,9 @@ class CameraPiPlugin(CameraPlugin):
     Plugin to control a Pi camera.
 
     .. warning::
-        This plugin is **DEPRECATED*, as it relies on the old ``picamera`` module.
+        This plugin is **DEPRECATED**, as it relies on the old ``picamera`` module.
-        On recent systems, it should be possible to access the Pi Camera through the FFmpeg or GStreamer integrations.
+        On recent systems, it should be possible to access the Pi Camera through
+        the ffmpeg or gstreamer integrations.
 
     """
 

platypush/plugins/light/hue/__init__.py

@@ -76,7 +76,7 @@ class LightHuePlugin(RunnablePlugin, LightEntityManager):
         """
         :param bridge: Bridge address or hostname
         :param lights: Default lights to be controlled (default: all)
-        :param groups Default groups to be controlled (default: all)
+        :param groups: Default groups to be controlled (default: all)
         :param poll_interval: How often the plugin should check the bridge for light
             updates (default: 20 seconds).
         :param config_file: Path to the phue configuration file containing the

platypush/plugins/serial/__init__.py

@@ -58,7 +58,7 @@ class SerialPlugin(SensorPlugin):
 
     def __init__(
         self,
-        device: Optional[str] = None,
+        device: str,
         baud_rate: int = 9600,
         max_size: int = 1 << 19,
         timeout: float = _default_lock_timeout,
@@ -67,7 +67,7 @@ class SerialPlugin(SensorPlugin):
         **kwargs,
     ):
         """
-        :param device: Device path (e.g. ``/dev/ttyUSB0`` or ``/dev/ttyACM0``)
+        :param device: Device path (e.g. ``/dev/ttyUSB0`` or ``/dev/ttyACM0``).
         :param baud_rate: Serial baud rate (default: 9600)
         :param max_size: Maximum size of a JSON payload (default: 512 KB). The
             plugin will keep reading bytes from the wire until it can form a
@@ -195,9 +195,6 @@ class SerialPlugin(SensorPlugin):
 
         :param device: Default device path override.
         :param baud_rate: Default baud rate override.
-        :param reset: By default, if a connection to the device is already open
-            then the current object will be returned. If ``reset=True``, the
-            connection will be reset and a new one will be created instead.
         """
         try:
             return self.__get_serial(device, baud_rate)
@@ -262,7 +259,6 @@ class SerialPlugin(SensorPlugin):
         """
 
         device, baud_rate = self._get_device_and_baud_rate(device, baud_rate)
-        data = None
 
         with get_lock(self.serial_lock, timeout=self._timeout) as serial_available:
             if serial_available:

platypush/plugins/zigbee/mqtt/__init__.py

@@ -112,8 +112,10 @@ class ZigbeeMqttPlugin(
 
           .. code-block:: shell
 
-             wget https://github.com/Koenkk/Z-Stack-firmware/raw/master\
+             # Check out the latest version of the coordinator firmware at
-                     /coordinator/Z-Stack_Home_1.2/bin/default/CC2531_DEFAULT_20201127.zip
+             # https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator
+
+             wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/<dir>/bin/default/<version>.zip
              unzip CC2531_DEFAULT_20201127.zip
              [sudo] cc-tool -e -w CC2531ZNP-Prod.hex
 
@@ -129,19 +131,18 @@ class ZigbeeMqttPlugin(
           .. code-block:: shell
 
              # Clone zigbee2mqtt repository
-             [sudo] git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
+             export ZIGBEE2MQTT_DIR="$HOME/zigbee2mqtt"
-             [sudo] chown -R pi:pi /opt/zigbee2mqtt  # Or whichever is your user
+             git clone https://github.com/Koenkk/zigbee2mqtt.git "$ZIGBEE2MQTT_DIR"
-
+             cd "$ZIGBEE2MQTT_DIR"
-             # Install dependencies (as user "pi")
+             # Install dependencies
-             cd /opt/zigbee2mqtt
              npm install
 
         - You need to have an MQTT broker running somewhere. If not, you can
           install `Mosquitto <https://mosquitto.org/>`_ through your package
           manager on any device in your network.
 
-        - Edit the ``/opt/zigbee2mqtt/data/configuration.yaml`` file to match
+        - Edit ``$ZIGBEE2MQTT_DIR/data/configuration.yaml`` file to match the configuration of
-          the configuration of your MQTT broker:
+          your MQTT broker:
 
           .. code-block:: yaml
 
@@ -169,7 +170,7 @@ class ZigbeeMqttPlugin(
 
           .. code-block:: shell
 
-              cd /opt/zigbee2mqtt
+              cd "$ZIGBEE2MQTT_DIR"
               npm start
 
         - If you have Zigbee devices that are paired to other bridges, unlink
@@ -205,7 +206,7 @@ class ZigbeeMqttPlugin(
         :param host: Default MQTT broker where ``zigbee2mqtt`` publishes its messages.
         :param port: Broker listen port (default: 1883).
         :param topic_prefix: Prefix for the published topics, as specified in
-            ``/opt/zigbee2mqtt/data/configuration.yaml`` (default: '``zigbee2mqtt``').
+            ``ZIGBEE2MQTT_DIR/data/configuration.yaml`` (default: '``zigbee2mqtt``').
         :param base_topic: Legacy alias for ``topic_prefix`` (default:
             '``zigbee2mqtt``').
         :param timeout: If the command expects from a response, then this