Updated docs.

VERSION.txt

@@ -1 +1 @@
-6.4.2-d
+6.4.3-d

docs/generate_command_signatures.py

@@ -94,6 +94,8 @@ def print_mapping(commands, excludes=None):
 
 
 # Overlay output.
+print(".. generated by generate_command_signatures.py")
+print("")
 
 print_heading("Common")
 print_description("Common commands are available to all overlays.")

docs/source/_data/cloc.csv

@@ -1,3 +1,3 @@
 files,language,blank,comment,code
-19,Python,876,759,1463
+21,Python,928,813,1516
-19,SUM,876,759,1463
+21,SUM,928,813,1516

docs/source/_includes/overlays.rst

@@ -1,3 +1,5 @@
+.. generated by generate_command_signatures.py
+
 Common
 ======
 
@@ -12,6 +14,7 @@ Use pip to install or uninstall a Python package.
 - op (str): The operation to perform; install, uninstall
 - upgrade (bool): Upgrade an installed package.
 - venv (str): The name of the virtual environment to load.
+- version (int): The Python version to use, e.g. ``2`` or ``3``.
 
 
 .. code-block:: ini
@@ -21,6 +24,7 @@ Use pip to install or uninstall a Python package.
     op: install
     upgrade: False
     venv: None
+    version: 3
 
 run
 ---
@@ -35,6 +39,38 @@ Run any statement.
     [run run command]
     run: statement
 
+slack
+-----
+
+Send a message to Slack.
+
+- message (str): The message to be sent.
+- url (str): The webhook URL. This is required. See documentation.
+
+
+.. code-block:: ini
+
+    [run slack command]
+    slack: message
+    url: None
+
+twist
+-----
+
+Send a message to Twist.
+
+- message (str): The message to be sent.
+- title (str): The message title.
+- url (str): The webhook URL. This is required. See documentation.
+
+
+.. code-block:: ini
+
+    [run twist command]
+    twist: message
+    title: Notice
+    url: None
+
 virtualenv
 ----------
 
@@ -587,6 +623,38 @@ Copy a file or directory.
     overwrite: False
     recursive: False
 
+dialog
+------
+
+Display a dialog message.
+
+- message (str): The message to be displayed.
+- height (int): The height of the dialog.
+- title (str): The title of the dialog.
+- width (int): The width of the dialog.
+
+
+.. code-block:: ini
+
+    [run dialog command]
+    dialog: message
+    height: 15
+    title: Message
+    width: 100
+
+echo
+----
+
+Echo a message.
+
+- message (str): The message to be printed to screen.
+
+
+.. code-block:: ini
+
+    [run echo command]
+    echo: message
+
 extract
 -------
 

docs/source/_includes/project-dependencies.rst

@@ -1,17 +1,37 @@
 Requirements
 ------------
 
-superpython
+jinja2
------------
+------
+
+
+**Install**
+
+.. code-block:: bash
+
+    pip install jinja2;
+
+pygments
+--------
+
+
+**Install**
+
+.. code-block:: bash
+
+    pip install pygments;
+
+python-commonkit
+----------------
 
 
 **URLs**
 
-- `Source Code <https://github.com/develmaycare/superpython>`_
+- `Source Code <https://github.com/develmaycare/python-commonkit>`_
 
 **Install**
 
 .. code-block:: bash
 
-    pip install git+https://github.com/develmaycare/superpython;
+    pip install python-commonkit;
 

docs/source/commands.rst

@@ -37,3 +37,50 @@ Commands
     NOTES
 
     This command is used to parse configuration files and output the commands.
+
+Using the Tease Command
+=======================
+
+The ``tease`` command may be used to parse a configuration file, providing additional utilities for working with commands.
+
+The ``path`` argument defaults to ``commands.ini``.
+
+Context Variables May be Provided on the Command Line
+-----------------------------------------------------
+
+To supply context variables on the command line:
+
+.. code-block:: bash
+
+    tease -C domain_name:example.com -C domain_tld:example_com
+
+Loading Context Variables from a File
+-------------------------------------
+
+Context variables may be loaded from a file:
+
+.. code-block:: ini
+
+    [domain]
+    name = example.com
+    tld = example_com
+
+The variables above are available as ``section_key``. For example, ``domain_name`` is ``example.com``.
+
+.. code-block:: bash
+
+    tease -V variables.ini
+
+Setting Common Options for All Commands
+---------------------------------------
+
+Rather than include a common parameter in the configuration file, it is possible to specify a common option on the command line.
+
+.. code-block:: bash
+
+    tease -O sudo:yes
+
+The Difference Between Variables and Options
+--------------------------------------------
+
+Variables are used to pre-process configuration files as templates, while common options are passed to *all* command instances.

docs/source/getting-started.rst

@@ -37,11 +37,7 @@ TODO
 FAQs
 ====
 
-**Question?**
-
-Answer.
-
 Have a question? `Just ask`_!
 
-.. _Just ask: https://{{ project_domain }}/contact
+.. _Just ask: https://develmaycare.com/contact/?product=Script%20Tease
 

docs/source/how-to.rst

@@ -30,7 +30,7 @@ For overlays that represent an operating system, the ``command_exists()`` functi
 2) Define Command Function
 --------------------------
 
-The purpose of each function is to provide an interface for instantiating a :py:class`scripttease.library.commands.base.Command` instance. The example below is taken from the ``posix`` module.
+The purpose of each function is to provide an interface for instantiating a :py:class:`scripttease.library.commands.base.Command` instance. The example below is taken from the ``posix`` module.
 
 .. code-block:: python
 
@@ -62,6 +62,9 @@ The arguments and any specific keyword arguments are automatically used by the p
 
 Each function *must* also accept ``**kwargs`` and should set a default for ``comment`` as above.
 
+.. important::
+    Rather than the usual Spinx-based documentation, define the docstring as shown above. This is used to automatically create the documentation for the command.
+
 3) Add Functions to the Mapping
 -------------------------------
 
@@ -96,9 +99,16 @@ Additionally, for an operating system overlay, you may wish to import other mapp
     MAPPINGS.update(DJANGO_MAPPINGS)
     MAPPINGS.update(PGSQL_MAPPINGS)
 
+4) Update Documentation
+-----------------------
+
+Add the command mappings to the ``docs/generate_command_signatures.py`` file. See the script for more details.
+
 Export Commands as a Script
 ===========================
 
+You can export commands as a read-to-use script. For example:
+
 .. code-block:: python
 
     config = Config("commands.ini")
@@ -108,3 +118,61 @@ Export Commands as a Script
 
     script = config.as_script()
     print(script)
+
+Post a Message to Slack
+=======================
+
+The slack function may be used to send a message to a Slack channel. This uses the Incoming Webhooks feature, which requires some additional setup.
+
+.. note::
+    The following steps were accurate as of September 2020.
+
+**1.** Log in to Slack and go to `Your Apps`_.
+
+.. _Your Apps: https://api.slack.com/apps
+
+**2.** Create a new Slack app.
+
+**3.** On the next page, select Incoming Webhooks and then toggle activation.
+
+.. image:: /_static/images/slack-1.jpg
+
+**4.** Next click Add new Webhook to Workspace and select the channel to which the message will be posted.
+
+.. image:: /_static/images/slack-2.jpg
+
+.. image:: /_static/images/slack-3.jpg
+
+**5.** Copy the URL for the new webhook to use as the ``url`` parameter for the Slack command.
+
+.. code-block:: ini
+
+    [send a message to slack]
+    slack: "This is a test message."
+    url: the URL you created goes here
+
+Post a Message to Twist
+=======================
+
+The twist function may be used to send a message to Twist, which requires some additional setup.
+
+.. note::
+    The following steps were accurate as of September 2020.
+
+**1.** Log in to Twist and from the profile menu go to Add Integrations. Then click on Build and "Add a new integration".
+
+**2.** Provide the requested info.
+
+.. image:: _static/images/twist-1.png
+
+**3.** After submitting this info, go to Installation. Select a channel and who to notify. Then click "Install integration".
+
+.. image:: _static/images/twist-2.png
+
+**4.** Copy the "Post content manually" URL for use in your configuration file.
+
+.. code-block:: ini
+
+    [post a message to twist]
+    twist: "This is a test message."
+    url: the URL you created goes here

docs/source/introduction.rst

@@ -7,7 +7,7 @@ Introduction
 Overview
 ========
 
-Script Tease is a library and command line tool for generating commands programmatically or using configuration files.
+Script Tease is a library and command line tool for generating commands programmatically or (especially) using configuration files.
 
 Concepts
 ========
@@ -26,15 +26,18 @@ Overlays
 An *overlay* is a set of command meta functions that define the capabilities of a specific operating system.
 
 .. note::
-    At present, the only fully defined overlays are for Cent OS and Ubuntu.
+    At present, the only fully defined operating system overlays are for Cent OS and Ubuntu.
 
 See :ref:`topics-overlays`.
 
 Terms and Definitions
 =====================
 
-term
+command
-    Definition.
+    When used in Script Tease documentation, this is a command instance which contains the properties and parameters for a command line statement.
+
+statement
+    A specific statement (string) to be executed. A *statement* is contained within a *command*.
 
 License
 =======

docs/source/topics-configuration.rst

@@ -32,8 +32,8 @@ An example file:
 Notes regarding this format:
 
 - This is the standard format for Python's ConfigParser. If you prefer, you may use ``=`` instead of ``:``.
-- The first line is the INI section and is used as the default comment.
+- The first part of each command is the INI section and is used as the default comment.
-- The command name must be the *first* option in the section.
+- The command name *must* be the *first* option in the section.
 - The arguments for the command appear as the value of the first option in the section. Arguments are separated by a
   space.
 - Arguments that should be treated as a single value should be enclosed in double quotes.
@@ -50,16 +50,12 @@ All commands support the following common parameters:
 - ``comment``: A comment regarding the command.
 - ``condition``: A condition for execution. For example, ``! -f /path/to/some/file.txt``
 - ``cd``: The path from which a command should be executed.
-- ``environments``: A string or list of strings indicating the operational environments in which the command runs. This
+- ``environments``: A string or list of comma-separated strings indicating the operational environments in which the command runs. This is *not* used by default, but may be used to programmatically filter commands for a specific environment. For example, development versus live.
-  is *not* used by default, but may be used to programmatically filter commands for a specific environment. For example,
-  development versus live.
 - ``prefix``: A statement to be added prior to executing the command.
 - ``register``: A variable name to which the the success or failure (exit code) of the statement is captured.
-- ``shell``: The shell used to run the commands. For example, ``/bin/bash``. This is generally not important, but can
+- ``shell``: The shell used to run the commands. For example, ``/bin/bash``. This is generally not important, but can be a problem when attempting to execute some commands (such as Django management commands).
-  be a problem when attempting to execute some commands (such as Django management commands).
 - ``stop``: ``True`` indicates no other commands should be executed if the given command fails.
-- ``sudo``: ``True`` indicates the command should be automatically prefixed with ``sudo``. If provided as a string, the
+- ``sudo``: ``True`` indicates the command should be automatically prefixed with ``sudo``. If provided as a string, the command is also prefixed with a specific user name.
-  command is also prefixed with a specific user name.
 - ``tags``: A list of tags used to classify the command.
 
 Defining an "Itemized" Command
@@ -112,23 +108,3 @@ Then with a config instance:
     for command in config.get_commands():
         print(command.get_statement(cd=True))
         print("")
-
-Using the Tease Command
-=======================
-
-The ``tease`` command may be used to parse a configuration file, providing additional utilities for working with commands. See :ref:`commands`.
-
-The ``path`` argument defaults to ``commands.ini``.
-
-Loading Variables from a File
------------------------------
-
-Context variables may be loaded from a file:
-
-.. code-block:: ini
-
-    [domain]
-    name = example.com
-    tld = example_com
-
-The variables above are available as ``section_key``. For example, ``domain_name`` is ``example.com``.

docs/source/topics-overlays.rst

@@ -1,10 +1,10 @@
 .. _topics-overlays:
 
-*******
+********
-Overlay
+Overlays
-*******
+********
 
-An overlay is a collection of functions that provide an interface to command creation.
+An overlay is a collection of functions that provide an interface to command creation. An overlay allows configuration files to specify commands in a generic way. When the file is loaded, an overlay may be specified which Script Tease uses to generate commands that are specific to a given operating system.
 
 There are currently four (4) general and re-usable overlays:
 

scripttease/library/commands/base.py

@@ -8,8 +8,6 @@ class Command(object):
                  prefix=None, register=None, shell=None, stop=False, sudo=None, tags=None, **kwargs):
         """Initialize a command.
 
-        :param name: The name of the command.
-
         :param statement: The statement to be executed.
         :type statement: str
 
@@ -186,7 +184,7 @@ class ItemizedCommand(object):
 
         :param args: The itemized arguments. ``$item`` should be included.
 
-        :param kwargs: Keyword arguments are passed to the command class upon instantiation.
+        Keyword arguments are passed to the command class upon instantiation.
 
         """
         self.args = args