From 02a63172e9207aba130b5c838dacd9459055301e Mon Sep 17 00:00:00 2001
From: Shawn Davis <shawn@ptltd.co>
Date: Fri, 1 Jan 2021 18:27:12 -0500
Subject: [PATCH] Updated docs.

---
 VERSION.txt                  |  2 +-
 docs/source/_data/cloc.csv   |  4 +--
 docs/source/how-to.rst       | 58 ++++++++++++++++++++++++++++++++++++
 docs/source/introduction.rst |  2 ++
 scripttease/version.py       |  6 ++--
 5 files changed, 66 insertions(+), 6 deletions(-)

diff --git a/VERSION.txt b/VERSION.txt
index 1d42024..23863d3 100644
--- a/VERSION.txt
+++ b/VERSION.txt
@@ -1 +1 @@
-6.7.1
\ No newline at end of file
+6.8.1
\ No newline at end of file
diff --git a/docs/source/_data/cloc.csv b/docs/source/_data/cloc.csv
index 1960bc6..a28a7b4 100644
--- a/docs/source/_data/cloc.csv
+++ b/docs/source/_data/cloc.csv
@@ -1,3 +1,3 @@
 files,language,blank,comment,code
-22,Python,1050,921,1740
-22,SUM,1050,921,1740
+22,Python,1123,979,1844
+22,SUM,1123,979,1844
diff --git a/docs/source/how-to.rst b/docs/source/how-to.rst
index 4d9eb8d..1e11500 100644
--- a/docs/source/how-to.rst
+++ b/docs/source/how-to.rst
@@ -176,3 +176,61 @@ The twist function may be used to send a message to Twist, which requires some a
     [post a message to twist]
     twist: "This is a test message."
     url: the URL you created goes here
+
+Use Script Tease With Common Kit
+================================
+
+Since the focus of Script Tease is to convert plain text instructions into valid command line statements, it does *not* provide support for executing those statements either locally or remotely. However, The shell component of `python-commonkit`_ *does* provide support for executing commands in local POSIX environments.
+
+.. _python-commonkit: https://docs.develmaycare.com/en/python-commonkit/stable/components/#module-commonkit.shell
+
+Here is an example of how to use these packages together:
+
+.. code-block:: python
+
+    from commonkit.shell import Command
+    from scripttease.parsers.utils import load_commands
+
+    def execute(step):
+        command = Command(
+            step.statement,
+            comment=step.comment,
+            path=step.cd,
+            prefix=step.prefix,
+            shell=step.shell
+        )
+
+        # Sudo is a different class, but identical in behavior.
+        command.sudo = step.sudo
+
+        if command.run():
+            print("[success] %s" % step.comment)
+        else:
+            print("[failure] %s" % step.comment)
+            if step.stop:
+                print("I can't go on: %s" % command.error)
+                exit(command.code)
+
+    # Load SCRIPT TEASE commands from an INI file. These are instances of either Command or ItemizedCommand found in
+    # scripttease.library.commands
+    steps = load_commands("path/to/steps.ini")
+
+    # A failure to load results in None.
+    if steps is None:
+        print("Failed to load steps.")
+        exit(1)
+
+    # Iterate through each step to create a COMMON KIT command.
+    for step in steps:
+
+        # To preview ...
+        # print(step.get_statement(cd=True))
+
+        if step.is_itemized:
+            for substep in step.get_commands():
+                execute(substep)
+        else:
+            execute(step)
+
+Common Kit is already a dependency of Script Tease so it is installed by default. The ``execute()`` function is a shortcut that helps deal with itemized commands.  The path (``step.cd``) is automatically handled by Common Kit's Command class.
+
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
index b802ba4..9af58ff 100644
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -9,6 +9,8 @@ Overview
 
 Script Tease is a library and command line tool for generating commands programmatically or (especially) using configuration files.
 
+The primary focus (and limit) is to convert plain text instructions into valid command line statements for a given platform (see `Overlays`_). It does *not* provide support for executing those statements.
+
 Concepts
 ========
 
diff --git a/scripttease/version.py b/scripttease/version.py
index 0303ce4..771da44 100644
--- a/scripttease/version.py
+++ b/scripttease/version.py
@@ -1,5 +1,5 @@
-DATE = "2020-12-16"
-VERSION = "6.7.1"
+DATE = "2021-01-01"
+VERSION = "6.8.1"
 MAJOR = 6
-MINOR = 7
+MINOR = 8
 PATCH = 1