Updated docs.

development
Shawn Davis 4 years ago
parent a975bb2145
commit bd65941add
  1. 2
      VERSION.txt
  2. 2
      docs/generate_command_signatures.py
  3. 4
      docs/source/_data/cloc.csv
  4. 68
      docs/source/_includes/overlays.rst
  5. 28
      docs/source/_includes/project-dependencies.rst
  6. BIN
      docs/source/_static/images/twist-1.png
  7. BIN
      docs/source/_static/images/twist-2.png
  8. 47
      docs/source/commands.rst
  9. 6
      docs/source/getting-started.rst
  10. 70
      docs/source/how-to.rst
  11. 11
      docs/source/introduction.rst
  12. 34
      docs/source/topics-configuration.rst
  13. 8
      docs/source/topics-overlays.rst
  14. 4
      scripttease/library/commands/base.py

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

@ -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.")

@ -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

1 files language blank comment code
2 19 21 Python 876 928 759 813 1463 1516
3 19 21 SUM 876 928 759 813 1463 1516

@ -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
-------

@ -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;

Binary file not shown.

After

Width:  |  Height:  |  Size: 111 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 181 KiB

@ -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.

@ -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

@ -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

@ -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
=======

@ -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``.

@ -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:

@ -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

Loading…
Cancel
Save