From 4e153a2872a5b6162bf52213484e881bf5f82ba2 Mon Sep 17 00:00:00 2001
From: Paul Barker <pbarker@konsulko.com>
Date: Fri, 6 Nov 2020 12:50:18 +0100
Subject: [PATCH] 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   | 17 +++++++++++++++++
 kas/plugins/build.py | 13 +++++++++++--
 kas/plugins/shell.py | 17 +++++++++++++++--
 3 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/docs/userguide.rst b/docs/userguide.rst
index 7550cf8..e2f2e76 100644
--- a/docs/userguide.rst
+++ b/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
 ---------------------
 
diff --git a/kas/plugins/build.py b/kas/plugins/build.py
index f1861c0..8d288cb 100644
--- a/kas/plugins/build.py
+++ b/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
diff --git a/kas/plugins/shell.py b/kas/plugins/shell.py
index a2958b1..a7e067f 100644
--- a/kas/plugins/shell.py
+++ b/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