Enable fail-on-error for doc builds

.readthedocs.yml

@@ -13,4 +13,5 @@ python:
     - docs
 
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
+  fail_on_warning: true

docs/conf.py

@@ -188,6 +188,8 @@
 apidoc_output_dir = "api"
 apidoc_excluded_paths = ["tests", "**/test_*", "**/tests"]
 apidoc_separate_modules = True
+apidoc_toc_file = False
+
 autodoc_member_order = "groupwise"
 autodoc_inherit_docstrings = True
 autodoc_default_options = {"inherited-members": True}

docs/contributing.rst

@@ -115,10 +115,11 @@ Development checklist
 ---------------------
 
 1. All device classes are derived from either :class:`miio.device.Device` (for MiIO)
-   or :class:`miio.miot_device.MiotDevice` (for MiOT) (:ref:`Minimal example`).
+   or :class:`miio.miot_device.MiotDevice` (for MiOT) (:ref:`minimal_example`).
 2. All commands and their arguments should be decorated with `@command` decorator,
    which will make them accessible to `miiocli` (:ref:`miiocli`).
-3. All implementations must define :ref:`Device._supported_models` variable in the class
+3. All implementations must either include a model-keyed ``_mappings`` list (for MiOT),
+   or define ``Device._supported_models`` variable in the class (for MiIO).
    listing the known models (as reported by `info()`).
 4. Status containers is derived from `DeviceStatus` class and all properties should
    have type annotations for their return values.
@@ -127,13 +128,17 @@ Development checklist
    will be generated automatically.
 
 
+.. _minimal_example:
+
 Minimal example
 ~~~~~~~~~~~~~~~
 
 .. TODO::
     Add or link to an example.
 
 
+.. _miiocli:
+
 miiocli integration
 ~~~~~~~~~~~~~~~~~~~
 

docs/legacy_token_extraction.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _legacy_token_extraction:
 
 Legacy methods for obtaining tokens

docs/push_server.rst

@@ -9,7 +9,7 @@ and calling the registered callbacks accordingly.
 .. note::
 
     While the eventing has been so far tested only on gateway devices, other devices that allow scene definitions on the
-    mobile app may potentially support this functionality. See :ref:`how to obtain event information<events_obtain>` for details
+    mobile app may potentially support this functionality. See :ref:`how to obtain event information<obtain_event_info>` for details
     how to check if your target device supports this functionality.
 
 
@@ -189,7 +189,7 @@ to retrieve the necessary information for that event.
 
 Most times this information will be enough, however the :class:`miio.EventInfo` class allows for additional information.
 For example, on Zigbee sub-devices you also need to define `source_sid` and `source_model`,
-see :ref:`button press <_button_press_example>` for an example.
+see :ref:`button press <button_press_example>` for an example.
 See the :class:`PushServer.EventInfo` for more detailed documentation.
 
 

miio/airqualitymonitor_miot.py

@@ -87,26 +87,25 @@ class DisplayTemperatureUnitCGDN1(enum.Enum):
 
 
 class AirQualityMonitorCGDN1Status(DeviceStatus):
-    """
-    Container of air quality monitor CGDN1 status.
-
-    {
-      'humidity': 34,
-      'pm25': 18,
-      'pm10': 21,
-      'temperature': 22.8,
-      'co2': 468,
-      'battery': 37,
-      'charging_state': 0,
-      'voltage': 3564,
-      'start_time': 0,
-      'end_time': 0,
-      'monitoring_frequency': 1,
-      'screen_off': 300,
-      'device_off': 60,
-      'temperature_unit': 'c'
-    }
-
+    """Container of air quality monitor CGDN1 status.
+
+    Example::
+        {
+        'humidity': 34,
+        'pm25': 18,
+        'pm10': 21,
+        'temperature': 22.8,
+        'co2': 468,
+        'battery': 37,
+        'charging_state': 0,
+        'voltage': 3564,
+        'start_time': 0,
+        'end_time': 0,
+        'monitoring_frequency': 1,
+        'screen_off': 300,
+        'device_off': 60,
+        'temperature_unit': 'c'
+        }
     """
 
     def __init__(self, data):

miio/device.py

@@ -232,7 +232,7 @@ def get_properties(
 
         :param list properties: List of properties to query from the device.
         :param int max_properties: Number of properties that can be requested at once.
-        :return List of property values.
+        :return: List of property values.
         """
         _props = properties.copy()
         values = []

miio/extract_tokens.py

@@ -54,13 +54,13 @@ def read_android_yeelight(db) -> Iterator[DeviceConfig]:
 class BackupDatabaseReader:
     """Main class for reading backup files.
 
-    Example:
-    .. code-block:: python
+    Example::
+        .. code-block:: python
 
-        r = BackupDatabaseReader()
-        devices = r.read_tokens("/tmp/database.sqlite")
-        for dev in devices:
-            print("Got %s with token %s" % (dev.ip, dev.token)
+            r = BackupDatabaseReader()
+            devices = r.read_tokens("/tmp/database.sqlite")
+            for dev in devices:
+                print("Got %s with token %s" % (dev.ip, dev.token)
     """
 
     def __init__(self, dump_raw=False):

miio/huizuo.py

@@ -192,22 +192,24 @@ def heat_level(self) -> Optional[int]:
 class Huizuo(MiotDevice):
     """A basic support for Huizuo Lamps.
 
-    Example: response of a Huizuo Pisces For Bedroom (huayi.light.pis123)
+    Example response of a Huizuo Pisces For Bedroom (huayi.light.pis123)::
+
         {'id': 1, 'result': [
           {'did': '', 'siid': 2, 'piid': 1, 'code': 0, 'value': False},
           {'did': '', 'siid': 2, 'piid': 2, 'code': 0, 'value': 94},
           {'did': '', 'siid': 2, 'piid': 3, 'code': 0, 'value': 6400}
           ]
         }
 
-    Explanation (line-by-line):
+    Explanation (line-by-line)::
+
         power = '{"siid":2,"piid":1}' values = true,false
         brightless(%) = '{"siid":2,"piid":2}' values = 1-100
         color temperature(Kelvin) = '{"siid":2,"piid":3}' values = 3000-6400
 
-    This is basic response for all HUIZUO lamps
+    This is basic response for all HUIZUO lamps.
     Also some models supports additional properties, like for Fan or Heating management.
-    If your device does't support some properties, the 'None' will be returned
+    If your device does't support some properties, the 'None' will be returned.
     """
 
     mapping = _MAPPING

miio/integrations/airpurifier/zhimi/airpurifier_miot.py

@@ -272,32 +272,32 @@ class LedBrightness(enum.Enum):
 class AirPurifierMiotStatus(DeviceStatus):
     """Container for status reports from the air purifier.
 
-    Mi Air Purifier 3/3H (zhimi.airpurifier.mb3) response (MIoT format)
-
-    [
-        {'did': 'power', 'siid': 2, 'piid': 2, 'code': 0, 'value': True},
-        {'did': 'fan_level', 'siid': 2, 'piid': 4, 'code': 0, 'value': 1},
-        {'did': 'mode', 'siid': 2, 'piid': 5, 'code': 0, 'value': 2},
-        {'did': 'humidity', 'siid': 3, 'piid': 7, 'code': 0, 'value': 38},
-        {'did': 'temperature', 'siid': 3, 'piid': 8, 'code': 0, 'value': 22.299999},
-        {'did': 'aqi', 'siid': 3, 'piid': 6, 'code': 0, 'value': 2},
-        {'did': 'filter_life_remaining', 'siid': 4, 'piid': 3, 'code': 0, 'value': 45},
-        {'did': 'filter_hours_used', 'siid': 4, 'piid': 5, 'code': 0, 'value': 1915},
-        {'did': 'buzzer', 'siid': 5, 'piid': 1, 'code': 0, 'value': False},
-        {'did': 'buzzer_volume', 'siid': 5, 'piid': 2, 'code': -4001},
-        {'did': 'led_brightness', 'siid': 6, 'piid': 1, 'code': 0, 'value': 1},
-        {'did': 'led', 'siid': 6, 'piid': 6, 'code': 0, 'value': True},
-        {'did': 'child_lock', 'siid': 7, 'piid': 1, 'code': 0, 'value': False},
-        {'did': 'favorite_level', 'siid': 10, 'piid': 10, 'code': 0, 'value': 2},
-        {'did': 'favorite_rpm', 'siid': 10, 'piid': 7, 'code': 0, 'value': 770},
-        {'did': 'motor_speed', 'siid': 10, 'piid': 8, 'code': 0, 'value': 769},
-        {'did': 'use_time', 'siid': 12, 'piid': 1, 'code': 0, 'value': 6895800},
-        {'did': 'purify_volume', 'siid': 13, 'piid': 1, 'code': 0, 'value': 222564},
-        {'did': 'average_aqi', 'siid': 13, 'piid': 2, 'code': 0, 'value': 2},
-        {'did': 'filter_rfid_tag', 'siid': 14, 'piid': 1, 'code': 0, 'value': '81:6b:3f:32:84:4b:4'},
-        {'did': 'filter_rfid_product_id', 'siid': 14, 'piid': 3, 'code': 0, 'value': '0:0:31:31'},
-        {'did': 'app_extra', 'siid': 15, 'piid': 1, 'code': 0, 'value': 0}
-    ]
+    Mi Air Purifier 3/3H (zhimi.airpurifier.mb3) response (MIoT format)::
+
+        [
+            {'did': 'power', 'siid': 2, 'piid': 2, 'code': 0, 'value': True},
+            {'did': 'fan_level', 'siid': 2, 'piid': 4, 'code': 0, 'value': 1},
+            {'did': 'mode', 'siid': 2, 'piid': 5, 'code': 0, 'value': 2},
+            {'did': 'humidity', 'siid': 3, 'piid': 7, 'code': 0, 'value': 38},
+            {'did': 'temperature', 'siid': 3, 'piid': 8, 'code': 0, 'value': 22.299999},
+            {'did': 'aqi', 'siid': 3, 'piid': 6, 'code': 0, 'value': 2},
+            {'did': 'filter_life_remaining', 'siid': 4, 'piid': 3, 'code': 0, 'value': 45},
+            {'did': 'filter_hours_used', 'siid': 4, 'piid': 5, 'code': 0, 'value': 1915},
+            {'did': 'buzzer', 'siid': 5, 'piid': 1, 'code': 0, 'value': False},
+            {'did': 'buzzer_volume', 'siid': 5, 'piid': 2, 'code': -4001},
+            {'did': 'led_brightness', 'siid': 6, 'piid': 1, 'code': 0, 'value': 1},
+            {'did': 'led', 'siid': 6, 'piid': 6, 'code': 0, 'value': True},
+            {'did': 'child_lock', 'siid': 7, 'piid': 1, 'code': 0, 'value': False},
+            {'did': 'favorite_level', 'siid': 10, 'piid': 10, 'code': 0, 'value': 2},
+            {'did': 'favorite_rpm', 'siid': 10, 'piid': 7, 'code': 0, 'value': 770},
+            {'did': 'motor_speed', 'siid': 10, 'piid': 8, 'code': 0, 'value': 769},
+            {'did': 'use_time', 'siid': 12, 'piid': 1, 'code': 0, 'value': 6895800},
+            {'did': 'purify_volume', 'siid': 13, 'piid': 1, 'code': 0, 'value': 222564},
+            {'did': 'average_aqi', 'siid': 13, 'piid': 2, 'code': 0, 'value': 2},
+            {'did': 'filter_rfid_tag', 'siid': 14, 'piid': 1, 'code': 0, 'value': '81:6b:3f:32:84:4b:4'},
+            {'did': 'filter_rfid_product_id', 'siid': 14, 'piid': 3, 'code': 0, 'value': '0:0:31:31'},
+            {'did': 'app_extra', 'siid': 15, 'piid': 1, 'code': 0, 'value': 0}
+        ]
     """
 
     def __init__(self, data: Dict[str, Any], model: str) -> None:

miio/integrations/humidifier/deerma/airhumidifier_jsqs.py

@@ -47,21 +47,21 @@ class OperationMode(enum.Enum):
 class AirHumidifierJsqsStatus(DeviceStatus):
     """Container for status reports from the air humidifier.
 
-    Xiaomi Mi Smart Humidifer S (deerma.humidifier.[jsqs, jsq5]) respone (MIoT format)
-
-    [
-        {'did': 'power', 'siid': 2, 'piid': 1, 'code': 0, 'value': True},
-        {'did': 'fault', 'siid': 2, 'piid': 2, 'code': 0, 'value': 0},
-        {'did': 'mode', 'siid': 2, 'piid': 5, 'code': 0, 'value': 1},
-        {'did': 'target_humidity', 'siid': 2, 'piid': 6, 'code': 0, 'value': 50},
-        {'did': 'relative_humidity', 'siid': 3, 'piid': 1, 'code': 0, 'value': 40},
-        {'did': 'temperature', 'siid': 3, 'piid': 7, 'code': 0, 'value': 22.7},
-        {'did': 'buzzer', 'siid': 5, 'piid': 1, 'code': 0, 'value': False},
-        {'did': 'led_light', 'siid': 6, 'piid': 1, 'code': 0, 'value': True},
-        {'did': 'water_shortage_fault', 'siid': 7, 'piid': 1, 'code': 0, 'value': False},
-        {'did': 'tank_filed', 'siid': 7, 'piid': 2, 'code': 0, 'value': False},
-        {'did': 'overwet_protect', 'siid': 7, 'piid': 3, 'code': 0, 'value': False}
-    ]
+    Xiaomi Mi Smart Humidifer S (deerma.humidifier.[jsqs, jsq5]) response (MIoT format)::
+
+        [
+            {'did': 'power', 'siid': 2, 'piid': 1, 'code': 0, 'value': True},
+            {'did': 'fault', 'siid': 2, 'piid': 2, 'code': 0, 'value': 0},
+            {'did': 'mode', 'siid': 2, 'piid': 5, 'code': 0, 'value': 1},
+            {'did': 'target_humidity', 'siid': 2, 'piid': 6, 'code': 0, 'value': 50},
+            {'did': 'relative_humidity', 'siid': 3, 'piid': 1, 'code': 0, 'value': 40},
+            {'did': 'temperature', 'siid': 3, 'piid': 7, 'code': 0, 'value': 22.7},
+            {'did': 'buzzer', 'siid': 5, 'piid': 1, 'code': 0, 'value': False},
+            {'did': 'led_light', 'siid': 6, 'piid': 1, 'code': 0, 'value': True},
+            {'did': 'water_shortage_fault', 'siid': 7, 'piid': 1, 'code': 0, 'value': False},
+            {'did': 'tank_filed', 'siid': 7, 'piid': 2, 'code': 0, 'value': False},
+            {'did': 'overwet_protect', 'siid': 7, 'piid': 3, 'code': 0, 'value': False}
+        ]
     """
 
     def __init__(self, data: Dict[str, Any]) -> None:

miio/integrations/humidifier/zhimi/airhumidifier_miot.py

@@ -70,28 +70,28 @@ class PressedButton(enum.Enum):
 class AirHumidifierMiotStatus(DeviceStatus):
     """Container for status reports from the air humidifier.
 
-    Xiaomi Smartmi Evaporation Air Humidifier 2 (zhimi.humidifier.ca4) respone (MIoT format)
-
-    [
-        {'did': 'power', 'siid': 2, 'piid': 1, 'code': 0, 'value': True},
-        {'did': 'fault', 'siid': 2, 'piid': 2, 'code': 0, 'value': 0},
-        {'did': 'mode', 'siid': 2, 'piid': 5, 'code': 0, 'value': 0},
-        {'did': 'target_humidity', 'siid': 2, 'piid': 6, 'code': 0, 'value': 50},
-        {'did': 'water_level', 'siid': 2, 'piid': 7, 'code': 0, 'value': 127},
-        {'did': 'dry', 'siid': 2, 'piid': 8, 'code': 0, 'value': False},
-        {'did': 'use_time', 'siid': 2, 'piid': 9, 'code': 0, 'value': 5140816},
-        {'did': 'button_pressed', 'siid': 2, 'piid': 10, 'code': 0, 'value': 2},
-        {'did': 'speed_level', 'siid': 2, 'piid': 11, 'code': 0, 'value': 790},
-        {'did': 'temperature', 'siid': 3, 'piid': 7, 'code': 0, 'value': 22.7},
-        {'did': 'fahrenheit', 'siid': 3, 'piid': 8, 'code': 0, 'value': 72.8},
-        {'did': 'humidity', 'siid': 3, 'piid': 9, 'code': 0, 'value': 39},
-        {'did': 'buzzer', 'siid': 4, 'piid': 1, 'code': 0, 'value': False},
-        {'did': 'led_brightness', 'siid': 5, 'piid': 2, 'code': 0, 'value': 2},
-        {'did': 'child_lock', 'siid': 6, 'piid': 1, 'code': 0, 'value': False},
-        {'did': 'actual_speed', 'siid': 7, 'piid': 1, 'code': 0, 'value': 0},
-        {'did': 'power_time', 'siid': 7, 'piid': 3, 'code': 0, 'value': 18520},
-        {'did': 'clean_mode', 'siid': 7, 'piid': 5, 'code': 0, 'value': True}
-    ]
+    Xiaomi Smartmi Evaporation Air Humidifier 2 (zhimi.humidifier.ca4) respone (MIoT format)::
+
+        [
+            {'did': 'power', 'siid': 2, 'piid': 1, 'code': 0, 'value': True},
+            {'did': 'fault', 'siid': 2, 'piid': 2, 'code': 0, 'value': 0},
+            {'did': 'mode', 'siid': 2, 'piid': 5, 'code': 0, 'value': 0},
+            {'did': 'target_humidity', 'siid': 2, 'piid': 6, 'code': 0, 'value': 50},
+            {'did': 'water_level', 'siid': 2, 'piid': 7, 'code': 0, 'value': 127},
+            {'did': 'dry', 'siid': 2, 'piid': 8, 'code': 0, 'value': False},
+            {'did': 'use_time', 'siid': 2, 'piid': 9, 'code': 0, 'value': 5140816},
+            {'did': 'button_pressed', 'siid': 2, 'piid': 10, 'code': 0, 'value': 2},
+            {'did': 'speed_level', 'siid': 2, 'piid': 11, 'code': 0, 'value': 790},
+            {'did': 'temperature', 'siid': 3, 'piid': 7, 'code': 0, 'value': 22.7},
+            {'did': 'fahrenheit', 'siid': 3, 'piid': 8, 'code': 0, 'value': 72.8},
+            {'did': 'humidity', 'siid': 3, 'piid': 9, 'code': 0, 'value': 39},
+            {'did': 'buzzer', 'siid': 4, 'piid': 1, 'code': 0, 'value': False},
+            {'did': 'led_brightness', 'siid': 5, 'piid': 2, 'code': 0, 'value': 2},
+            {'did': 'child_lock', 'siid': 6, 'piid': 1, 'code': 0, 'value': False},
+            {'did': 'actual_speed', 'siid': 7, 'piid': 1, 'code': 0, 'value': 0},
+            {'did': 'power_time', 'siid': 7, 'piid': 3, 'code': 0, 'value': 18520},
+            {'did': 'clean_mode', 'siid': 7, 'piid': 5, 'code': 0, 'value': True}
+        ]
     """
 
     def __init__(self, data: Dict[str, Any]) -> None:

miio/integrations/vacuum/dreame/dreamevacuum_miot.py

@@ -211,35 +211,36 @@ def _get_cleaning_mode_enum_class(model):
 class DreameVacuumStatus(DeviceStatusContainer):
     """Container for status reports from the dreame vacuum.
 
-    Dreame vacuum respone
-    {
-        'battery_level': 100,
-        'brush_left_time': 260,
-        'brush_left_time2': 200,
-        'brush_life_level': 90,
-        'brush_life_level2': 90,
-        'charging_state': 1,
-        'cleaning_area': 22,
-        'cleaning_mode': 2,
-        'cleaning_time': 17,
-        'device_fault': 0,
-        'device_status': 6,
-        'filter_left_time': 120,
-        'filter_life_level': 40,
-        'first_clean_time': 1620154830,
-        'operating_mode': 6,
-        'start_time': '22:00',
-        'stop_time': '08:00',
-        'timer_enable': True,
-        'timezone': 'Europe/Berlin',
-        'total_clean_area': 205,
-        'total_clean_time': 186,
-        'total_clean_times': 21,
-        'voice_package': 'DR0',
-        'volume': 65,
-        'water_box_carriage_status': 0,
-        'water_flow': 3
-    }
+    Dreame vacuum example response::
+
+        {
+            'battery_level': 100,
+            'brush_left_time': 260,
+            'brush_left_time2': 200,
+            'brush_life_level': 90,
+            'brush_life_level2': 90,
+            'charging_state': 1,
+            'cleaning_area': 22,
+            'cleaning_mode': 2,
+            'cleaning_time': 17,
+            'device_fault': 0,
+            'device_status': 6,
+            'filter_left_time': 120,
+            'filter_life_level': 40,
+            'first_clean_time': 1620154830,
+            'operating_mode': 6,
+            'start_time': '22:00',
+            'stop_time': '08:00',
+            'timer_enable': True,
+            'timezone': 'Europe/Berlin',
+            'total_clean_area': 205,
+            'total_clean_time': 186,
+            'total_clean_times': 21,
+            'voice_package': 'DR0',
+            'volume': 65,
+            'water_box_carriage_status': 0,
+            'water_flow': 3
+        }
     """
 
     def __init__(self, data, model):