8000 Update documentation structure and start migrating to markdown (#934) · python-kasa/python-kasa@6616d68 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6616d68

Browse files
sdb9696sdb9696
authored
Update documentation structure and start migrating to markdown (#934)
Starts structuring the documentation library usage into Tutorials, Guides, Explanations and Reference. Continues migrating new docs from rst to markdown. Extends the test framework discovery mocks to allow easy writing and testing of code examples.
1 parent 7671564 commit 6616d68

31 files changed

+617
-322
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<h2 align="center">python-kasa</h2>
1+
# python-kasa
22

33
[![PyPI version](https://badge.fury.io/py/python-kasa.svg)](https://badge.fury.io/py/python-kasa)
44
[![Build Status](https://github.com/python-kasa/python-kasa/actions/workflows/ci.yml/badge.svg)](https://github.com/python-kasa/python-kasa/actions/workflows/ci.yml)

‎docs/source/conf.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@
3737
"myst_parser",
3838
]
3939

40+
myst_enable_extensions = [
41+
"colon_fence",
42+
]
43+
4044
# Add any paths that contain templates here, relative to this directory.
4145
templates_path = ["_templates"]
4246

‎docs/source/deprecated.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Deprecated API
2+
3+
```{currentmodule} kasa
4+
```
5+
The page contains the documentation for the deprecated library API that only works with the older kasa devices.
6+
7+
If you want to continue to use the old API for older devices,
8+
you can use the classes in the `iot` module to avoid deprecation warnings.
9+
10+
```py
11+
from kasa.iot import IotDevice, IotBulb, IotPlug, IotDimmer, IotStrip, IotLightStrip
12+
```
13+
14+
15+
```{toctree}
16+
:maxdepth: 2
17+
18+
smartdevice
19+
smartbulb
20+
smartplug
21+
smartdimmer
22+
smartstrip
23+
smartlightstrip
24+
```

‎docs/source/discover.rst

Lines changed: 0 additions & 62 deletions
This file was deleted.

‎docs/source/guides.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# How-to Guides
2+
3+
This page contains guides of how to perform common actions using the library.
4+
5+
## Discover devices
6+
7+
```{eval-rst}
8+
.. automodule:: kasa.discover
9+
```
10+
11+
## Connect without discovery
12+
13+
```{eval-rst}
14+
.. automodule:: kasa.deviceconfig
15+
```
16+
17+
## Get Energy Consumption and Usage Statistics
18+
19+
:::{note}
20+
In order to use the helper methods to calculate the statistics correctly, your devices need to have correct time set.
21+
The devices use NTP and public servers from [NTP Pool Project](https://www.ntppool.org/) to synchronize their time.
22+
:::
23+
24+
### Energy Consumption
25+
26+
The availability of energy consumption sensors depend on the device.
27+
While most of the bulbs support it, only specific switches (e.g., HS110) or strips (e.g., HS300) support it.
28+
You can use {attr}`~Device.has_emeter` to check for the availability.
29+
30+
31+
### Usage statistics
32+
33+
You can use {attr}`~Device.on_since` to query for the time the device has been turned on.
34+
Some devices also support reporting the usage statistics on daily or monthly basis.
35+
You can access this information using through the usage module ({class}`kasa.modules.Usage`):
36+
37+
```py
38+
dev = SmartPlug("127.0.0.1")
39+
usage = dev.modules["usage"]
40+
print(f"Minutes on this month: {usage.usage_this_month}")
41+
print(f"Minutes on today: {usage.usage_today}")
42+
```

‎docs/source/index.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
```{include} ../../README.md
2+
```
3+
4+
```{toctree}
5+
:maxdepth: 2
6+
7+
Home <self>
8+
cli
9+
library
10+
contribute
11+
SUPPORTED
12+
```

‎docs/source/index.rst

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎docs/source/library.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Library usage
2+
3+
```{currentmodule} kasa
4+
```
5+
The page contains all information about the library usage:
6+
7+
```{toctree}
8+
:maxdepth: 2
9+
10+
tutorial
11+
guides
12+
topics
13+
reference
14+
deprecated
15+
```

‎docs/source/reference.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# API Reference
2+
3+
```{currentmodule} kasa
4+
```
5+
6+
## Discover
7+
8+
```{eval-rst}
9+
.. autoclass:: kasa.Discover
10+
:members:
11+
```
12+
13+
## Device
14+
15+
```{eval-rst}
16+
.. autoclass:: kasa.Device
17+
:members:
18+
:undoc-members:
19+
```
20+
21+
## Modules and Features
22+
23+
```{eval-rst}
24+
.. autoclass:: kasa.Module
25+
:noindex:
26+
:members:
27+
:inherited-members:
28+
:undoc-members:
29+
```
30+
31+
```{eval-rst}
32+
.. automodule:: kasa.interfaces
33+
:noindex:
34+
:members:
35+
:inherited-members:
36+
:undoc-members:
37+
```
38+
39+
```{eval-rst}
40+
.. autoclass:: kasa.Feature
41+
:noindex:
42+
:members:
43+
:inherited-members:
44+
:undoc-members:
45+
```
46+
47+
## Protocols and transports
48+
49+
```{eval-rst}
50+
.. autoclass:: kasa.protocol.BaseProtocol
51+
:members:
52+
:inherited-members:
53+
:undoc-members:
54+
```
55+
56+
```{eval-rst}
57+
.. autoclass:: kasa.iotprotocol.IotProtocol
58+
:members:
59+
:inherited-members:
60+
:undoc-members:
61+
```
62+
63+
```{eval-rst}
64+
.. autoclass:: kasa.smartprotocol.SmartProtocol
65+
:members:
66+
:inherited-members:
67+
:undoc-members:
68+
```
69+
70+
```{eval-rst}
71+
.. autoclass:: kasa.protocol.BaseTransport
72+
:members:
73+
:inherited-members:
74+
:undoc-members:
75+
```
76+
77+
```{eval-rst}
78+
.. autoclass:: kasa.xortransport.XorTransport
79+
:members:
80+
:inherited-members:
81+
:undoc-members:
82+
```
83+
84+
```{eval-rst}
85+
.. autoclass:: kasa.klaptransport.KlapTransport
86+
:members:
87+
:inherited-members:
88+
:undoc-members:
89+
```
90+
91+
```{eval-rst}
92+
.. autoclass:: kasa.klaptransport.KlapTransportV2
93+
:members:
94+
:inherited-members:
95+
:undoc-members:
96+
```
97+
98+
```{eval-rst}
99+
.. autoclass:: kasa.aestransport.AesTransport
100+
:members:
101+
:inherited-members:
102+
:undoc-members:
103+
```
104+
105+
## Errors and exceptions
106+
107+
```{eval-rst}
108+
.. autoclass:: kasa.exceptions.KasaException
109+
:members:
110+
:undoc-members:
111+
```
112+
113+
```{eval-rst}
114+
.. autoclass:: kasa.exceptions.DeviceError
115+
:members:
116+
:undoc-members:
117+
```
118+
119+
```{eval-rst}
120+
.. autoclass:: kasa.exceptions.AuthenticationError
121+
:members:
122+
:undoc-members:
123+
```
124+
125+
```{eval-rst}
126+
.. autoclass:: kasa.exceptions.UnsupportedDeviceError
127+
:members:
128+
:undoc-members:
129+
```
130+
131+
```{eval-rst}
132+
.. autoclass:: kasa.exceptions.TimeoutError
133+
:members:
134+
:undoc-members:

0 commit comments

Comments
 (0)
0