Update docs for new FeatureAttribute behaviour (#1365)

Co-authored-by: Teemu R. <tpr@iki.fi>

docs/source/featureattributes.md

@@ -0,0 +1,13 @@
+Some modules have attributes that may not be supported by the device.
+These attributes will be annotated with a `FeatureAttribute` return type.
+For example:
+
+```py
+    @property
+    def hsv(self) -> Annotated[HSV, FeatureAttribute()]:
+        """Return the current HSV state of the bulb."""
+```
+
+You can test whether a `FeatureAttribute` is supported by the device with {meth}`kasa.Module.has_feature`
+or {meth}`kasa.Module.get_feature` which will return `None` if not supported.
+Calling these methods on attributes not annotated with a `FeatureAttribute` return type will return an error.

docs/source/reference.md

@@ -13,11 +13,13 @@
 
 ## Device
 
+% N.B. Credentials clashes with autodoc
 
 ```{eval-rst}
 .. autoclass:: Device
     :members:
     :undoc-members:
+    :exclude-members: Credentials
 ```
 
 
@@ -28,7 +30,6 @@
 .. autoclass:: Credentials
     :members:
     :undoc-members:
-    :noindex:
 ```
 
 
@@ -61,15 +62,11 @@
 
 ```{eval-rst}
 .. autoclass:: Module
-    :noindex:
     :members:
-    :inherited-members:
-    :undoc-members:
 ```
 
 ```{eval-rst}
 .. autoclass:: Feature
-    :noindex:
     :members:
     :inherited-members:
     :undoc-members:
@@ -77,7 +74,6 @@
 
 ```{eval-rst}
 .. automodule:: kasa.interfaces
-    :noindex:
     :members:
     :inherited-members:
     :undoc-members:
@@ -85,64 +81,29 @@
 
 ## Protocols and transports
 
+
 ```{eval-rst}
-.. autoclass:: kasa.protocols.BaseProtocol
+.. automodule:: kasa.protocols
     :members:
-    :inherited-members:
+    :imported-members:
     :undoc-members:
+    :exclude-members: SmartErrorCode
+    :no-index:
 ```
 
 ```{eval-rst}
-.. autoclass:: kasa.protocols.IotProtocol
+.. automodule:: kasa.transports
     :members:
-    :inherited-members:
+    :imported-members:
     :undoc-members:
+    :no-index:
 ```
 
-```{eval-rst}
-.. autoclass:: kasa.protocols.SmartProtocol
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
-
-```{eval-rst}
-.. autoclass:: kasa.transports.BaseTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
-
-```{eval-rst}
-.. autoclass:: kasa.transports.XorTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
-
-```{eval-rst}
-.. autoclass:: kasa.transports.KlapTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
-
-```{eval-rst}
-.. autoclass:: kasa.transports.KlapTransportV2
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
-
-```{eval-rst}
-.. autoclass:: kasa.transports.AesTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
 
 ## Errors and exceptions
 
+
+
 ```{eval-rst}
 .. autoclass:: kasa.exceptions.KasaException
     :members:
@@ -171,3 +132,4 @@
 .. autoclass:: kasa.exceptions.TimeoutError
     :members:
     :undoc-members:
+```

docs/source/topics.md

@@ -80,14 +80,17 @@ This can be done using the {attr}`~kasa.Device.internal_state` property.
 ## Modules and Features
 
 The functionality provided by all {class}`~kasa.Device` instances is (mostly) done inside separate modules.
-While the individual device-type specific classes provide an easy access for the most import features,
+While the device class provides easy access for most device related attributes,
-you can also access individual modules through {attr}`kasa.Device.modules`.
+for components like `light` and `camera` you can access the module through {attr}`kasa.Device.modules`.
-You can get the list of supported modules for a given device instance using {attr}`~kasa.Device.supported_modules`.
+The module names are handily available as constants on {class}`~kasa.Module` and will return type aware values from the collection.
 
-```{note}
+Features represent individual pieces of functionality within a module like brightness, hsv and temperature within a light module.
-If you only need some module-specific information,
+They allow for instrospection and can be accessed through {attr}`kasa.Device.features`.
-you can call the wanted method on the module to avoid using {meth}`~kasa.Device.update`.
+Attributes can be accessed via a `Feature` or a module attribute depending on the use case.
-```
+Modules tend to provide richer functionality but using the features does not require an understanding of the module api.
+
+:::{include} featureattributes.md
+:::
 
 (topics-protocols-and-transports)=
 ## Protocols and Transports
@@ -137,96 +140,3 @@ The base exception for all library errors is {class}`KasaException <kasa.excepti
 - If the library encounters and unsupported deviceit raises an {class}`UnsupportedDeviceError <kasa.exceptions.UnsupportedDeviceError>`.
 - If the device fails to respond within a timeout the library raises a {class}`TimeoutError <kasa.exceptions.TimeoutError>`.
 - All other failures will raise the base {class}`KasaException <kasa.exceptions.KasaException>` class.
-
-<!-- Commenting out this section keeps git seeing the change as a rename.
-
-API documentation for modules and features
-******************************************
-
-.. autoclass:: kasa.Module
-    :noindex:
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. automodule:: kasa.interfaces
-    :noindex:
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.Feature
-    :noindex:
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-
-
-API documentation for protocols and transports
-**********************************************
-
-.. autoclass:: kasa.protocols.BaseProtocol
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.protocols.IotProtocol
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.protocols.SmartProtocol
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.transports.BaseTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.transports.XorTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.transports.KlapTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.transports.KlapTransportV2
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: kasa.transports.AesTransport
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-API documentation for errors and exceptions
-*******************************************
-
-.. autoclass:: kasa.exceptions.KasaException
-    :members:
-    :undoc-members:
-
-.. autoclass:: kasa.exceptions.DeviceError
-    :members:
-    :undoc-members:
-
-.. autoclass:: kasa.exceptions.AuthenticationError
-    :members:
-    :undoc-members:
-
-.. autoclass:: kasa.exceptions.UnsupportedDeviceError
-    :members:
-    :undoc-members:
-
-.. autoclass:: kasa.exceptions.TimeoutError
-    :members:
-    :undoc-members:
-
--->

kasa/module.py

@@ -21,6 +21,9 @@ check for the existence of the module:
 >>>     print(light.brightness)
 100
 
+.. include:: ../featureattributes.md
+   :parser: myst_parser.sphinx_
+
 To see whether a device supports specific functionality, you can check whether the
 module has that feature: