diff --git a/VERSION.txt b/VERSION.txt index 5030bbb..880c0dd 100644 --- a/VERSION.txt +++ b/VERSION.txt @@ -1 +1 @@ -6.4.2-d \ No newline at end of file +6.4.3-d \ No newline at end of file diff --git a/docs/generate_command_signatures.py b/docs/generate_command_signatures.py index a609759..6befdb2 100755 --- a/docs/generate_command_signatures.py +++ b/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.") diff --git a/docs/source/_data/cloc.csv b/docs/source/_data/cloc.csv index e26b5c0..f9173c7 100644 --- a/docs/source/_data/cloc.csv +++ b/docs/source/_data/cloc.csv @@ -1,3 +1,3 @@ files,language,blank,comment,code -19,Python,876,759,1463 -19,SUM,876,759,1463 +21,Python,928,813,1516 +21,SUM,928,813,1516 diff --git a/docs/source/_includes/overlays.rst b/docs/source/_includes/overlays.rst index 12f7751..ce2d34c 100644 --- a/docs/source/_includes/overlays.rst +++ b/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 ------- diff --git a/docs/source/_includes/project-dependencies.rst b/docs/source/_includes/project-dependencies.rst index 7743817..73a38eb 100644 --- a/docs/source/_includes/project-dependencies.rst +++ b/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 `_ +- `Source Code `_ **Install** .. code-block:: bash - pip install git+https://github.com/develmaycare/superpython; + pip install python-commonkit; diff --git a/docs/source/_static/images/twist-1.png b/docs/source/_static/images/twist-1.png new file mode 100644 index 0000000..a2806e4 Binary files /dev/null and b/docs/source/_static/images/twist-1.png differ diff --git a/docs/source/_static/images/twist-2.png b/docs/source/_static/images/twist-2.png new file mode 100644 index 0000000..deb31ef Binary files /dev/null and b/docs/source/_static/images/twist-2.png differ diff --git a/docs/source/commands.rst b/docs/source/commands.rst index e04a4cd..2dcbc60 100644 --- a/docs/source/commands.rst +++ b/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. diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index a89b3d3..3f4260c 100644 --- a/docs/source/getting-started.rst +++ b/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 diff --git a/docs/source/how-to.rst b/docs/source/how-to.rst index 1447201..4d9eb8d 100644 --- a/docs/source/how-to.rst +++ b/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 diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 7dad2d0..b802ba4 100644 --- a/docs/source/introduction.rst +++ b/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 - Definition. +command + 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 ======= diff --git a/docs/source/topics-configuration.rst b/docs/source/topics-configuration.rst index 82d0505..0cdc107 100644 --- a/docs/source/topics-configuration.rst +++ b/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 command name must be the *first* option in the section. +- 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 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 - is *not* used by default, but may be used to programmatically filter commands for a specific environment. For example, - development versus live. +- ``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. - ``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 - be a problem when attempting to execute some commands (such as Django management commands). +- ``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). - ``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 - command is also prefixed with a specific user name. +- ``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. - ``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``. diff --git a/docs/source/topics-overlays.rst b/docs/source/topics-overlays.rst index 864aa4b..8ada8b6 100644 --- a/docs/source/topics-overlays.rst +++ b/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: diff --git a/scripttease/library/commands/base.py b/scripttease/library/commands/base.py index 9155d51..54ccd17 100644 --- a/scripttease/library/commands/base.py +++ b/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