docs: Fix warnings and update CLI documentation

docs/api/nwp500.rst

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    nwp500.cli
+   nwp500.mqtt
 
 Submodules
 ----------
@@ -28,6 +29,14 @@ nwp500.auth module
    :show-inheritance:
    :undoc-members:
 
+nwp500.command\_decorators module
+---------------------------------
+
+.. automodule:: nwp500.command_decorators
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 nwp500.config module
 --------------------
 
@@ -36,106 +45,106 @@ nwp500.config module
    :show-inheritance:
    :undoc-members:
 
-nwp500.constants module
------------------------
+nwp500.converters module
+------------------------
 
-.. automodule:: nwp500.constants
+.. automodule:: nwp500.converters
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.encoding module
-----------------------
+nwp500.device\_capabilities module
+----------------------------------
 
-.. automodule:: nwp500.encoding
+.. automodule:: nwp500.device_capabilities
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.events module
---------------------
+nwp500.device\_info\_cache module
+---------------------------------
 
-.. automodule:: nwp500.events
+.. automodule:: nwp500.device_info_cache
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.exceptions module
-------------------------
+nwp500.encoding module
+----------------------
 
-.. automodule:: nwp500.exceptions
+.. automodule:: nwp500.encoding
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.models module
---------------------
+nwp500.enums module
+-------------------
 
-.. automodule:: nwp500.models
+.. automodule:: nwp500.enums
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_client module
---------------------------
+nwp500.events module
+--------------------
 
-.. automodule:: nwp500.mqtt_client
+.. automodule:: nwp500.events
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_command\_queue module
-----------------------------------
+nwp500.exceptions module
+------------------------
 
-.. automodule:: nwp500.mqtt_command_queue
+.. automodule:: nwp500.exceptions
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_connection module
-------------------------------
+nwp500.factory module
+---------------------
 
-.. automodule:: nwp500.mqtt_connection
+.. automodule:: nwp500.factory
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_device\_control module
------------------------------------
+nwp500.field\_factory module
+----------------------------
 
-.. automodule:: nwp500.mqtt_device_control
+.. automodule:: nwp500.field_factory
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_periodic module
-----------------------------
+nwp500.models module
+--------------------
 
-.. automodule:: nwp500.mqtt_periodic
+.. automodule:: nwp500.models
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_reconnection module
---------------------------------
+nwp500.mqtt\_events module
+--------------------------
 
-.. automodule:: nwp500.mqtt_reconnection
+.. automodule:: nwp500.mqtt_events
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_subscriptions module
----------------------------------
+nwp500.temperature module
+-------------------------
 
-.. automodule:: nwp500.mqtt_subscriptions
+.. automodule:: nwp500.temperature
    :members:
    :show-inheritance:
    :undoc-members:
 
-nwp500.mqtt\_utils module
--------------------------
+nwp500.topic\_builder module
+----------------------------
 
-.. automodule:: nwp500.mqtt_utils
+.. automodule:: nwp500.topic_builder
    :members:
    :show-inheritance:
    :undoc-members:

docs/conf.py

@@ -78,6 +78,7 @@
 # Suppress warnings for classes/functions exported in multiple modules
 suppress_warnings = [
     "ref.python",  # Suppress "more than one target found" warnings
+    "py.duplicate",  # Suppress all "duplicate" warnings including duplicate_description
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -289,4 +290,17 @@
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
 }
 
+# Suppress duplicate object description warnings from re-exported classes
+import logging
+
+class DuplicateWarningFilter(logging.Filter):
+    def filter(self, record):
+        # Suppress "duplicate object description" warnings
+        return "duplicate object description" not in record.getMessage()
+
+# Install the filter when Sphinx initializes
+def setup(app):
+    logger = logging.getLogger("sphinx")
+    logger.addFilter(DuplicateWarningFilter())
+
 print(f"loading configurations for {project} {version} ...", file=sys.stderr)

docs/enumerations.rst

@@ -10,6 +10,7 @@ Device Control Commands
 .. autoclass:: nwp500.enums.CommandCode
    :members:
    :undoc-members:
+   :no-index:
 
 These command IDs are used in MQTT control messages to change device settings
 and trigger actions. The most commonly used commands include:
@@ -37,6 +38,7 @@ OnOffFlag
 .. autoclass:: nwp500.enums.OnOffFlag
    :members:
    :undoc-members:
+   :no-index:
 
 Generic on/off flag used throughout status fields for power status, TOU status,
 recirculation status, vacation mode, anti-legionella, and other boolean settings.
@@ -49,6 +51,7 @@ Operation
 .. autoclass:: nwp500.enums.Operation
    :members:
    :undoc-members:
+   :no-index:
 
 Device operation state indicating overall device activity.
 
@@ -58,6 +61,7 @@ DhwOperationSetting
 .. autoclass:: nwp500.enums.DhwOperationSetting
    :members:
    :undoc-members:
+   :no-index:
 
 User-configured DHW heating mode preference. This determines which heat source(s)
 the device will use when heating is needed:
@@ -83,6 +87,7 @@ CurrentOperationMode
 .. autoclass:: nwp500.enums.CurrentOperationMode
    :members:
    :undoc-members:
+   :no-index:
 
 Real-time operational state (read-only). This reflects what the device is actually
 doing right now, which may differ from the configured mode setting:
@@ -106,6 +111,7 @@ HeatSource
 .. autoclass:: nwp500.enums.HeatSource
    :members:
    :undoc-members:
+   :no-index:
 
 Currently active heat source (read-only status). This reflects what the device
 is *currently* using, not what mode it's set to. In Hybrid mode, this field
@@ -117,6 +123,7 @@ DREvent
 .. autoclass:: nwp500.enums.DREvent
    :members:
    :undoc-members:
+   :no-index:
 
 Demand Response event status. Allows utilities to manage grid load by signaling
 water heaters to reduce consumption (shed) or pre-heat (load up) before peak periods.
@@ -127,6 +134,7 @@ WaterLevel
 .. autoclass:: nwp500.enums.WaterLevel
    :members:
    :undoc-members:
+   :no-index:
 
 Hot water level indicator displayed as gauge in app. IDs are non-sequential,
 likely represent bit positions for multi-level displays.
@@ -137,6 +145,7 @@ FilterChange
 .. autoclass:: nwp500.enums.FilterChange
    :members:
    :undoc-members:
+   :no-index:
 
 Air filter status for heat pump models. Indicates when air filter maintenance
 is needed.
@@ -147,6 +156,7 @@ RecirculationMode
 .. autoclass:: nwp500.enums.RecirculationMode
    :members:
    :undoc-members:
+   :no-index:
 
 Recirculation pump operation mode:
 
@@ -164,6 +174,7 @@ TouWeekType
 .. autoclass:: nwp500.enums.TouWeekType
    :members:
    :undoc-members:
+   :no-index:
 
 Day grouping for TOU schedules. Allows separate schedules for weekdays and
 weekends to account for different electricity rates and usage patterns.
@@ -174,6 +185,7 @@ TouRateType
 .. autoclass:: nwp500.enums.TouRateType
    :members:
    :undoc-members:
+   :no-index:
 
 Electricity rate period type. Device behavior can be configured for each period:
 
@@ -190,6 +202,7 @@ TemperatureType
 .. autoclass:: nwp500.enums.TemperatureType
    :members:
    :undoc-members:
+   :no-index:
 
 Temperature display unit preference (Celsius or Fahrenheit).
 
@@ -201,6 +214,7 @@ TempFormulaType
 .. autoclass:: nwp500.enums.TempFormulaType
    :members:
    :undoc-members:
+   :no-index:
 
 Temperature conversion formula type. Different device models use slightly different
 rounding algorithms when converting internal Celsius values to Fahrenheit:
@@ -219,6 +233,7 @@ UnitType
 .. autoclass:: nwp500.enums.UnitType
    :members:
    :undoc-members:
+   :no-index:
 
 Navien device/unit model types. Common values:
 
@@ -236,6 +251,7 @@ DeviceType
 .. autoclass:: nwp500.enums.DeviceType
    :members:
    :undoc-members:
+   :no-index:
 
 Communication device type (WiFi module model).
 
@@ -245,6 +261,7 @@ FirmwareType
 .. autoclass:: nwp500.enums.FirmwareType
    :members:
    :undoc-members:
+   :no-index:
 
 Firmware component types. Devices may have multiple firmware components that
 can be updated independently.
@@ -290,4 +307,4 @@ For detailed protocol documentation, see:
 
 - :doc:`protocol/device_status` - Status field definitions
 - :doc:`guides/time_of_use` - TOU scheduling and rate types
-- :doc:`protocol/control_commands` - Control command usage
+- :doc:`protocol/quick_reference` - Quick reference and control commands

docs/guides/mqtt_diagnostics.rst

@@ -1116,8 +1116,8 @@ Investigation Checklist
 See Also
 ========
 
-- :doc:`/docs/DEVICE_STATUS_FIELDS` - Device status field reference
-- :doc:`/docs/MQTT_CLIENT` - MQTT client API documentation
+- :doc:`../protocol/device_status` - Device status field reference
+- :doc:`../python_api/mqtt_client` - MQTT client API documentation
 
 External Resources
 

docs/protocol/mqtt_protocol.rst

@@ -770,8 +770,7 @@ Status Response
          "operationBusy": 2,
          "compUse": 2,
          "heatUpperUse": 1,
-         "errorCode": 0,
-         ...
+         "errorCode": 0
        }
      }
    }
@@ -796,8 +795,7 @@ Feature/Info Response
          "controller_sw_version": 184614912,
          "dhw_temperature_min": 75,
          "dhw_temperature_max": 130,
-         "energy_usage_use": 1,
-         ...
+         "energy_usage_use": 1
        }
      }
    }