Update docs with more howto examples (#968)

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

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.*
+:::

docs/source/guides.md

@@ -1,44 +1,16 @@
 # How-to Guides
 
-This page contains guides of how to perform common actions using the library.
+Guides of how to perform common actions using the library.
 
-## Discover devices
+```{toctree}
+:maxdepth: 2
 
-```{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/discover
+guides/connect
+guides/device
+guides/module
+guides/feature
+guides/light
+guides/strip
+guides/energy
 ```

docs/source/guides/connect.md

@@ -0,0 +1,10 @@
+(connect_target)=
+# Connect without discovery
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.deviceconfig
+    :noindex:
+```

docs/source/guides/device.md

@@ -0,0 +1,10 @@
+(device_target)=
+# Interact with devices
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.device
+    :noindex:
+```

docs/source/guides/discover.md

@@ -0,0 +1,11 @@
+(discover_target)=
+# Discover devices
+
+:::{include} ../codeinfo.md
+:::
+
+
+```{eval-rst}
+.. automodule:: kasa.discover
+    :noindex:
+```

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}")
+```

docs/source/guides/feature.md

@@ -0,0 +1,10 @@
+(feature_target)=
+# Interact with features
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.feature
+    :noindex:
+```

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:
+```

docs/source/guides/module.md

@@ -0,0 +1,10 @@
+(module_target)=
+# Interact with modules
+
+:::{include} ../codeinfo.md
+:::
+
+```{eval-rst}
+.. automodule:: kasa.module
+    :noindex:
+```

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:
+```

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,19 +40,19 @@
 
 
 ```{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:
 ```
@@ -65,7 +60,15 @@
 ## Modules and Features
 
 ```{eval-rst}
-.. autoclass:: kasa.Module
+.. autoclass:: Module
+    :noindex:
+    :members:
+    :inherited-members:
+    :undoc-members:
+```
+
+```{eval-rst}
+.. autoclass:: Feature
     :noindex:
     :members:
     :inherited-members:
@@ -80,14 +83,6 @@
     :undoc-members:
 ```
 
-```{eval-rst}
-.. autoclass:: kasa.Feature
-    :noindex:
-    :members:
-    :inherited-members:
-    :undoc-members:
-```
-
 ## Protocols and transports
 
 ```{eval-rst}

docs/source/tutorial.md

@@ -1,5 +1,8 @@
 # Getting started
 
+:::{include} codeinfo.md
+:::
+
 ```{eval-rst}
 .. automodule:: tutorial
     :members: