python-kasa · sdb9696 · Jun 19, 2024 · Jun 10, 2024 · Jun 10, 2024 · Jun 11, 2024
diff --git a/README.md b/README.md
@@ -173,16 +173,9 @@ Current state: {'total': 133.105, 'power': 108.223577, 'current': 0.54463, 'volt
 
 If you want to use this library in your own project, a good starting point is [the tutorial in the documentation](https://python-kasa.readthedocs.io/en/latest/tutorial.html).
 
-You can find several code examples in the API documentation of each of the implementation base classes, check out the [documentation for the base class shared by all supported devices](https://python-kasa.readthedocs.io/en/latest/smartdevice.html).
+You can find several code examples in the API documentation [How to guides](https://python-kasa.readthedocs.io/en/latest/guides.html).
 
-[The library design and module structure is described in a separate page](https://python-kasa.readthedocs.io/en/latest/design.html).
-
-The device type specific documentation can be found in their separate pages:
-* [Plugs](https://python-kasa.readthedocs.io/en/latest/smartplug.html)
-* [Bulbs](https://python-kasa.readthedocs.io/en/latest/smartbulb.html)
-* [Dimmers](https://python-kasa.readthedocs.io/en/latest/smartdimmer.html)
-* [Power strips](https://python-kasa.readthedocs.io/en/latest/smartstrip.html)
-* [Light strips](https://python-kasa.readthedocs.io/en/latest/smartlightstrip.html)
+Information about the library design and the way the devices work can be found in the [topics section](https://python-kasa.readthedocs.io/en/latest/topics.html).
 
 ## Contributing
 

diff --git a/docs/source/codeinfo.md b/docs/source/codeinfo.md
@@ -0,0 +1,26 @@
+
+:::{note}
+The library is fully async and methods that perform IO need to be run inside an async coroutine.
+Code examples assume you are following them inside `asyncio REPL`:
+```
+    $ python -m asyncio
+```
+Or the code is running inside an async function:
+```py
+import asyncio
+from kasa import Discover
+
+async def main():
+    dev = await Discover.discover_single("127.0.0.1",username="un@example.com",password="pw")
+    await dev.turn_on()
+    await dev.update()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+**All of your code needs to run inside the same event loop so only call `asyncio.run` once.**
+
+*The main entry point for the API is {meth}`~kasa.Discover.discover` and
+{meth}`~kasa.Discover.discover_single` which return Device objects.
+Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.*
+:::
diff --git a/docs/source/guides.md b/docs/source/guides.md
@@ -1,44 +1,16 @@
 # How-to Guides
 
-This page contains guides of how to perform common actions using the library.
-
-## Discover devices
-
-```{eval-rst}
-.. automodule:: kasa.discover
-    :noindex:
-```
-
-## Connect without discovery
-
-```{eval-rst}
-.. automodule:: kasa.deviceconfig
-    :noindex:
-```
-
-## Get Energy Consumption and Usage Statistics
-
-:::{note}
-In order to use the helper methods to calculate the statistics correctly, your devices need to have correct time set.
-The devices use NTP and public servers from [NTP Pool Project](https://www.ntppool.org/) to synchronize their time.
-:::
-
-### Energy Consumption
-
-The availability of energy consumption sensors depend on the device.
-While most of the bulbs support it, only specific switches (e.g., HS110) or strips (e.g., HS300) support it.
-You can use {attr}`~Device.has_emeter` to check for the availability.
-
-
-### Usage statistics
-
-You can use {attr}`~Device.on_since` to query for the time the device has been turned on.
-Some devices also support reporting the usage statistics on daily or monthly basis.
-You can access this information using through the usage module ({class}`kasa.modules.Usage`):
-
-```py
-dev = SmartPlug("127.0.0.1")
-usage = dev.modules["usage"]
-print(f"Minutes on this month: {usage.usage_this_month}")
-print(f"Minutes on today: {usage.usage_today}")
+Guides of how to perform common actions using the library.
+
+```{toctree}
+:maxdepth: 2
+
+guides/discover
+guides/connect
+guides/device
+guides/module
+guides/feature
+guides/light
+guides/strip
+guides/energy
 ```
diff --git a/docs/source/guides/connect.md b/docs/source/guides/connect.md
@@ -0,0 +1,10 @@
+(connect_target)=
+# Connect without discovery
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.deviceconfig
+    :noindex:
+```
diff --git a/docs/source/guides/device.md b/docs/source/guides/device.md
@@ -0,0 +1,10 @@
+(device_target)=
+# Interact with devices
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.device
+    :noindex:
+```
diff --git a/docs/source/guides/discover.md b/docs/source/guides/discover.md
@@ -0,0 +1,11 @@
+(discover_target)=
+# Discover devices
+
+:::{include} ../codeinfo.md
+:::
+
+
+```{eval-rst}
+.. automodule:: kasa.discover
+    :noindex:
+```
diff --git a/docs/source/guides/energy.md b/docs/source/guides/energy.md
@@ -0,0 +1,27 @@
+
+# Get Energy Consumption and Usage Statistics
+
+:::{note}
+In order to use the helper methods to calculate the statistics correctly, your devices need to have correct time set.
+The devices use NTP (123/UDP) and public servers from [NTP Pool Project](https://www.ntppool.org/) to synchronize their time.
+:::
+
+## Energy Consumption
+
+The availability of energy consumption sensors depend on the device.
+While most of the bulbs support it, only specific switches (e.g., HS110) or strips (e.g., HS300) support it.
+You can use {attr}`~Device.has_emeter` to check for the availability.
+
+
+## Usage statistics
+
+You can use {attr}`~Device.on_since` to query for the time the device has been turned on.
+Some devices also support reporting the usage statistics on daily or monthly basis.
+You can access this information using through the usage module ({class}`kasa.modules.Usage`):
+
+```py
+dev = SmartPlug("127.0.0.1")
+usage = dev.modules["usage"]
+print(f"Minutes on this month: {usage.usage_this_month}")
+print(f"Minutes on today: {usage.usage_today}")
+```
diff --git a/docs/source/guides/feature.md b/docs/source/guides/feature.md
@@ -0,0 +1,10 @@
+(feature_target)=
+# Interact with features
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.feature
+    :noindex:
+```
diff --git a/docs/source/guides/light.md b/docs/source/guides/light.md
@@ -0,0 +1,26 @@
+(light_target)=
+# Interact with lights
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.interfaces.light
+    :noindex:
+```
+
+(lightpreset_target)=
+## Presets
+
+```{eval-rst}
+.. automodule:: kasa.interfaces.lightpreset
+    :noindex:
+```
+
+(lighteffect_target)=
+## Effects
+
+```{eval-rst}
+.. automodule:: kasa.interfaces.lighteffect
+    :noindex:
+```
diff --git a/docs/source/guides/module.md b/docs/source/guides/module.md
@@ -0,0 +1,10 @@
+(module_target)=
+# Interact with modules
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.module
+    :noindex:
+```
diff --git a/docs/source/guides/strip.md b/docs/source/guides/strip.md
@@ -0,0 +1,10 @@
+(child_target)=
+# Interact with child devices
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.smart.modules.childdevice
+    :noindex:
+```
diff --git a/docs/source/reference.md b/docs/source/reference.md
@@ -3,18 +3,16 @@
 ## Discover
 
 
-```{module} kasa.discover
+```{module} kasa
 ```
 
 ```{eval-rst}
-.. autoclass:: kasa.Discover
+.. autoclass:: Discover
     :members:
 ```
 
 ## Device
 
-```{module} kasa.device
-```
 
 ```{eval-rst}
 .. autoclass:: Device
@@ -25,17 +23,14 @@
 
 ## Device Config
 
-```{module} kasa.credentials
-```
 
 ```{eval-rst}
 .. autoclass:: Credentials
     :members:
     :undoc-members:
+    :noindex:
 ```
 
-```{module} kasa.deviceconfig
-```
 
 ```{eval-rst}
 .. autoclass:: DeviceConfig
@@ -45,43 +40,43 @@
 
 
 ```{eval-rst}
-.. autoclass:: kasa.DeviceFamily
+.. autoclass:: DeviceFamily
     :members:
     :undoc-members:
 ```
 
 ```{eval-rst}
-.. autoclass:: kasa.DeviceConnection
+.. autoclass:: DeviceConnectionParameters
     :members:
     :undoc-members:
 ```
 
 ```{eval-rst}
-.. autoclass:: kasa.DeviceEncryption
+.. autoclass:: DeviceEncryptionType
     :members:
     :undoc-members:
 ```
 
 ## Modules and Features
 
 ```{eval-rst}
-.. autoclass:: kasa.Module
+.. autoclass:: Module
     :noindex:
     :members:
     :inherited-members:
     :undoc-members:
 ```
 
 ```{eval-rst}
-.. automodule:: kasa.interfaces
+.. autoclass:: Feature
     :noindex:
     :members:
     :inherited-members:
     :undoc-members:
 ```
 
 ```{eval-rst}
-.. autoclass:: kasa.Feature
+.. automodule:: kasa.interfaces
     :noindex:
     :members:
     :inherited-members:

diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md
@@ -1,5 +1,8 @@
 # Getting started
 
+:::{include} codeinfo.md
+:::
+
 ```{eval-rst}
 .. automodule:: tutorial
     :members:

diff --git a/docs/tutorial.py b/docs/tutorial.py
@@ -1,16 +1,5 @@
 # ruff: noqa
 """
-The kasa library is fully async and methods that perform IO need to be run inside an async couroutine.
-
-These examples assume you are following the tutorial inside `asyncio REPL` (python -m asyncio) or the code
-is running inside an async function (`async def`).
-
-
-The main entry point for the API is :meth:`~kasa.Discover.discover` and
-:meth:`~kasa.Discover.discover_single` which return Device objects.
-
-Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.
-
 >>> from kasa import Discover
 
 :func:`~kasa.Discover.discover` returns a dict[str,Device] of devices on your network: