plugins: Improve documentation of existing modules

The docstrings for the build and shell plugins are extended so that they
clearly describe each plugin and give brief examples of their use.

Also fix a typo in the build command help message.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>

docs/userguide.rst

@@ -65,6 +65,23 @@ Use Cases
     $ kas build kas-project.yml
 
 
+Plugins
+-------
+
+kas sub-commands are implemented by a series of plugins. Each plugin
+typically provides a single command.
+
+``build`` plugin
+~~~~~~~~~~~~~~~~
+
+.. automodule:: kas.plugins.build
+
+``shell`` plugin
+~~~~~~~~~~~~~~~~
+
+.. automodule:: kas.plugins.shell
+
+
 Project Configuration
 ---------------------
 

kas/plugins/build.py

@@ -20,7 +20,16 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 """
-    The build plugin for kas.
+    This plugin implements the ``kas build`` command.
+
+    When this command is executed, kas will checkout repositories, setup the
+    build environment and then invoke bitbake to build the targets selected
+    in the chosen config file.
+
+    For example, to build the configuration described in the file
+    ``kas-project.yml`` you could run::
+
+        kas build kas-project.yml
 """
 
 import logging
@@ -48,7 +57,7 @@ class Build:
     name = 'build'
     helpmsg = (
         'Checks out all necessary repositories and builds using bitbake as '
-        'specificed in the configuration file.'
+        'specified in the configuration file.'
     )
 
     @classmethod

kas/plugins/shell.py

@@ -20,8 +20,21 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 """
-    This module contains a kas plugin that opens a shell within the kas
-    environment
+    This plugin implements the ``kas shell`` command.
+
+    When this command is executed, kas will checkout repositories, setup the
+    build environment and then start a shell in the build environment. This
+    can be used to manually run ``bitbake`` with custom command line options
+    or to execute other commands such as ``runqemu``.
+
+    For example, to start a shell in the build environment for the file
+    ``kas-project.yml`` you could run::
+
+        kas shell kas-project.yml
+
+    Or to invoke qemu to test an image which has been built::
+
+        kas shell kas-project.yml -c 'runqemu'
 """
 
 import logging