Improve cli documentation for bulbs and power strips (#123)

README.md

@@ -115,6 +115,7 @@ or the `parse_pcap.py` script contained inside the `devtools` directory.
 
 * HS300
 * KP303
+* KP400
 
 ### Wall switches
 

docs/source/cli.rst

@@ -2,18 +2,23 @@ Command-line usage
 ==================
 
 The package is shipped with a console tool named kasa, please refer to ``kasa --help`` for detailed usage.
-The device to which the commands are sent is chosen by `KASA_HOST` environment variable or passing ``--host <address>`` as an option.
+The device to which the commands are sent is chosen by ``KASA_HOST`` environment variable or passing ``--host <address>`` as an option.
 To see what is being sent to and received from the device, specify option ``--debug``.
 
-To avoid discovering the devices when executing commands its type can be passed by specifying either ``--plug`` or ``--bulb``,
-if no type is given its type will be discovered automatically with a small delay.
-Some commands (such as reading energy meter values and setting color of bulbs) additional parameters are required,
-which you can find by adding ``--help`` after the command, e.g. ``kasa emeter --help`` or ``kasa hsv --help``.
+To avoid discovering the devices when executing commands its type can be passed as an option (e.g., ``--plug`` for plugs, ``--bulb`` for bulbs, ..).
+If no type is manually given, its type will be discovered automatically which causes a short delay.
 
 If no command is given, the ``state`` command will be executed to query the device state.
 
+.. note::
+
+    Some commands (such as reading energy meter values, changing bulb settings, or accessing individual sockets on smart strips) additional parameters are required,
+    which you can find by adding ``--help`` after the command, e.g. ``kasa emeter --help`` or ``kasa hsv --help``.
+    Refer to the device type specific documentation for more details.
+
+
 Provisioning
-~~~~~~~~~~~~
+************
 
 You can provision your device without any extra apps by using the ``kasa wifi`` command:
 
@@ -23,6 +28,6 @@ You can provision your device without any extra apps by using the ``kasa wifi``
 4. Join/change the network using ``kasa wifi join`` command, see ``--help`` for details.
 
 ``kasa --help``
-~~~~~~~~~~~~~~~
+***************
 
 .. program-output:: kasa --help

docs/source/conf.py

@@ -31,6 +31,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
     "sphinxcontrib.programoutput",
 ]
 
@@ -55,6 +56,8 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+todo_include_todos = True
+
 
 def setup(app):
     # add copybutton to hide the >>> prompts, see https://github.com/readthedocs/sphinx_rtd_theme/issues/167

docs/source/index.rst

@@ -1,6 +1,3 @@
-python-kasa documentation
-=========================
-
 .. mdinclude:: ../../README.md
 
 .. toctree::

docs/source/smartbulb.rst

@@ -1,6 +1,59 @@
 Bulbs
 ===========
 
+Supported features
+******************
+
+* Turning on and off
+* Setting brightness, color temperature, and color (in HSV)
+* Querying emeter information
+* Transitions
+
+Currently unsupported
+*********************
+
+* Setting the default transitions
+* Timers
+
+.. note::
+
+    Feel free to open a pull request to add support for more features!
+
+Transitions
+***********
+
+All commands changing the bulb state can be accompanied with a transition, e.g., to slowly fade the light off.
+The transition time is in milliseconds, 0 means immediate change.
+If no transition value is given, the default setting as configured for the bulb will be used.
+
+.. note::
+
+    Accepted values are command (and potentially bulb) specific, feel free to improve the documentation on accepted values.
+
+    **Example:** While KL130 allows at least up to 15 second transitions for smooth turning off transitions, turning it on will not be so smooth.
+
+Command-line usage
+******************
+
+All command-line commands can be used with transition period for smooth changes.
+
+
+**Example:** Turn the bulb off over a 15 second time period.
+
+.. code::
+
+    $ kasa --bulb --host <host> off --transition 15000
+
+**Example:** Change the bulb to red with 20% brightness over 15 seconds:
+
+.. code::
+
+    $ kasa --bulb --host <host> hsv 0 100 20 --transition 15000
+
+
+API documentation
+*****************
+
 .. autoclass:: kasa.SmartBulb
     :members:
     :undoc-members:

docs/source/smartdevice.rst

@@ -40,6 +40,10 @@ Refer to device type specific classes for more examples:
 * :class:`SmartDimmer`
 * :class:`SmartLightStrip`
 
+
+API documentation
+~~~~~~~~~~~~~~~~~
+
 .. autoclass:: kasa.SmartDevice
     :members:
     :undoc-members:

docs/source/smartdimmer.rst

@@ -1,6 +1,13 @@
 Dimmers
 =======
 
+.. note::
+
+    Feel free to open a pull request to improve the documentation!
+
+API documentation
+*****************
+
 .. autoclass:: kasa.SmartDimmer
     :members:
     :undoc-members:

docs/source/smartlightstrip.rst

@@ -1,6 +1,13 @@
 Light strips
 ============
 
+.. note::
+
+    Feel free to open a pull request to improve the documentation!
+
+API documentation
+*****************
+
 .. autoclass:: kasa.SmartLightStrip
     :members:
     :undoc-members:

docs/source/smartplug.rst

@@ -1,6 +1,14 @@
 Plugs
 =====
 
+.. note::
+
+    Feel free to open a pull request to improve the documentation!
+
+
+API documentation
+*****************
+
 .. autoclass:: kasa.SmartPlug
     :members:
     :undoc-members:

docs/source/smartstrip.rst

@@ -1,6 +1,37 @@
 Smart strips
 ============
 
+
+.. note::
+
+    The emeter feature is currently not implemented for smart strips. See https://github.com/python-kasa/python-kasa/issues/64 for details.
+
+.. note::
+
+    Feel free to open a pull request to improve the documentation!
+
+Command-line usage
+******************
+
+To command a single socket of a strip, you will need to specify it either by using ``--index`` or by using ``--name``.
+If not specified, the commands will act on the parent device: turning the strip off will turn off all sockets.
+
+**Example:** Turn off the first socket (the indexing starts from zero):
+
+.. code::
+
+   $ kasa --strip --host <host> on --index 0
+
+**Example:** Turn on the socket by name:
+
+.. code::
+
+   $ kasa --strip --host <host> off --name "Maybe Kitchen"
+
+
+API documentation
+*****************
+
 .. autoclass:: kasa.SmartStrip
     :members:
     :undoc-members: