Updated help documentation.

help/en/docs/cli.md

@@ -33,7 +33,7 @@ NOTES
 
 A nice benefit of using configuration for commands is that the information may be used to output documentation. This allows the automatic creation of an install guide or tutorial using exactly the same commands that would be used for the actual work.
 
-Additionally, Script Tease provides the [explain](commands/messages.md#explain) and [screenshot](commands/messages.md#screenshot) commands that help provide extra content for documentary output.
+Additionally, Script Tease provides the [explain](usage/messages.md#explain) and [screenshot](usage/messages.md#screenshot) commands that help provide extra content for documentary output.
 
 ```text
 usage: tease docs [-h] [-o= {html,md,plain,rst}] [-C= VARIABLES] [-i= STEPS_FILE] [-O= OPTIONS] [-P= {centos,ubuntu}]

help/en/docs/topics/steps-file.md

@@ -76,11 +76,6 @@ The comment comes from the section name (INI) or list name (YAML). It is include
 ; ...
 ```
 
-```yaml
-- this becomes the comment:
-  # ...
-```
-
 ### env
 
 The `env` option indicates the target environment (or environments) in which the statement should run. This is not used in command generation, but may be used for filtering.
@@ -136,13 +131,6 @@ shell: /bin/bash
 
 A `yes` indicates processing should stop if the statement fails to execute with success. If provided, it is included by default when the statement is generated, but may be suppressed. Additionally, when [register](#register) is defined, this option will use the result of the command to determine success. This option is also useful for programmatic execution.
 
-```yaml
-- check apache configuration:
-  apache: test
-  register: apache_ok
-  stop: yes
-```
-
 !!! warning
 
     Some commands do not provide a zero or non-zero exit code on success or failure. You should verify that the `stop` will actually be used.
@@ -163,39 +151,7 @@ sudo: yes
 
 ### tags
 
-`tags` is a comma separated list (INI) or list (YAML) of tag names. These may be used for filtering.
+`tags` is a comma separated list of tag names. These may be used for filtering.
-
-```yaml
-- install apache:
-  install: apache2
-  tags: [apache, web]
-  
-- enable wsgi:
-  apache.enable: mod_wsgi
-  tags: [apache, web]
-  
-- restart apache:
-  apache.restart:
-  tags: [apache, web]
-
-- run django checks:
-  django: check
-  tags: [django, python]
-
-- apply database migrations:
-  django: migrate
-  tags: [django, python]
-```
-
-With YAML, tags may also be specified like so:
-
-```yaml
-- install apache:
-  install: apache2
-  tags:
-    - apache
-    - web 
-```
 
 ## Ad Hoc Parameters
 

help/en/docs/usage/apache.md

@@ -0,0 +1,97 @@
+# Apache
+
+Summary: Work with Apache.
+
+## Available Commands
+
+### apache.disable_module
+
+Disable an Apache module. NOT SUPPORTED ACROSS ALL OPERATING SYSTEMS.
+
+```ini
+[disable ifenv]
+apache.disable_module: ifenv
+sudo: yes
+```
+
+### apache.disable_site
+
+Disable an Apache site (virtual host configuration). NOT SUPPORTED ACROSS ALL OPERATING SYSTEMS.
+
+```ini
+[disable the default apache site]
+apache.disable_site: 000-default
+sudo: yes
+```
+
+### apache.enable_module
+
+Enable an Apache module. NOT SUPPORTED ACROSS ALL OPERATING SYSTEMS.
+
+```ini
+[enable apache modules]
+apache.enable_module: $item
+items: ssl, rewrite, wsgi
+sudo: yes
+```
+
+### apache.enable_site
+
+Enable an Apache site (virtual host configuration). NOT SUPPORTED ACROSS ALL OPERATING SYSTEMS.
+
+```ini
+[enable the application configuration]
+apache.enable_site: example.app
+sudo: yes
+```
+
+### apache.reload
+
+Reload Apache configuration.
+
+```ini
+[reload apache]
+apache.reload:
+sudo: yes
+```
+
+### apache.restart
+
+Restart the Apache service.
+
+```ini
+[restart apache]
+apache.restart:
+sudo: yes
+```
+
+### apache.start
+
+Start the Apache service.
+
+```ini
+[start apache]
+apache.start:
+sudo: yes
+```
+
+### apache.stop
+
+Stop the Apache service.
+
+```ini
+[stop apache]
+apache.stop:
+sudo: yes
+```
+
+### apache.test
+
+Test Apache configuration.
+
+```ini
+[test apache configuration]
+apache.test:
+sudo: yes
+stop: yes
+```

help/en/docs/usage/centos.md

@@ -2,7 +2,15 @@
 
 ## Available Commands
 
-The `centos` profile incorporates commands from [Django](../commands/django.md), [messages](../commands/messages.md), [MySQL](../commands/mysql.md), [PHP](../commands/php.md), [POSIX](../commands/posix.md), [Postgres](../commands/pgsql.md), and [Python](../commands/python.md). 
+The `centos` profile incorporates commands from 
+
+- [Django](../commands/django.md)
+- [messages](../commands/messages.md)
+- [MySQL](../commands/mysql.md)
+- [PHP](../commands/php.md)
+- [POSIX](../commands/posix.md)
+- [Postgres](../commands/pgsql.md)
+- [Python](../commands/python.md)
 
 ### apache
 

help/en/docs/usage/django.md

@@ -28,7 +28,6 @@ django.dump: projects.Category
 indent: 4
 natural_foreign: yes
 natural_primary: yes
-
 ```
 
 `settings` becomes "--settings=tenants.example_com.settings". `indent` becomes "--indent=4". `natural_foreign` and `natural_primary` become "--natural-foreign" and "--natural-primary" respectively.
@@ -41,7 +40,6 @@ natural_primary: yes
 [run django checks]
 django.check:
 stop: yes
-
 ```
 
 ### collectstatic
@@ -82,7 +80,6 @@ django.dump: projects
 [dump project categories]
 django.dump: projects.Category
 path: local/projects/fixtures/default-categories.json
-
 ```
 
 ### loaddata
@@ -99,7 +96,6 @@ Load fixture data.
 [load project categories]
 django.load: projects
 path: local/projects/fixtures/default-categories.json
-
 ```
 
 ### migrate
@@ -128,5 +124,4 @@ This will generate a statement like:
 
 ```bash
 ./manage.py command_name --option-one="asdf" --option-two=1234 --option-three
-
 ```

help/en/docs/usage/messages.md

@@ -17,11 +17,6 @@ Use the dialog CLI to display a message.
 dialog: "This is a message."
 ```
 
-```yaml
-- send some feedback:
-  dialog: "This is a message."
-```
-
 !!! warning
 
     The dialog command line utility must be installed.
@@ -47,11 +42,6 @@ Display a simple message.
 echo: "This is a message."
 ```
 
-```yaml
-- send some feedback:
-  echo: "This is a message."
-```
-
 ### mattermost
 
 Send a message via Mattermost.
@@ -92,18 +82,12 @@ slack: "This is a message."
 url: https://subdomain.slack.com/path/to/your/integration
 ```
 
-```yaml
-- send some feedback:
-  slack: "This is a message."
-  url: https://subdomain.slack.com/path/to/your/integration
-```
-
 !!! note
-    You could easily define a variable for the Slack URL and set ``url: {{ slack_url }}`` to save some typing. See [variables](../config/variables.md).
+    You could easily define a variable for the Slack URL and set ``url: {{ slack_url }}`` to save some typing. See [variables](../topics/variables.md).
 
 Using the slack command requires setup from your Slack admin. The procedure will be something like the following:
 
-**1.** Log in to Slack and go to [Your Apps](https://api.slack.com/apps)
+**1.** Log in to Slack and go to [Your Apps](https://api.slack.com/apps).
 
 **2.** Create a new Slack app.
 
@@ -151,15 +135,9 @@ twist: "This is a message."
 url: https://subdomain.twist.com/path/to/your/integration
 ```
 
-```yaml
-- send some feedback:
-  twist: "This is a message."
-  url: https://subdomain.twist.com/path/to/your/integration
-```
-
 !!! note
 
-    As with Slack, you could easily define a variable for the Twist URL and set ``url: {{ twist_url }}``. See [variables](../config/variables.md).
+    As with Slack, you could easily define a variable for the Twist URL and set ``url: {{ twist_url }}``. See [variables](../topics/variables.md).
 
 Using the twist command requires setup on your Twist account. The procedure will be something like the following:
 

help/en/docs/usage/mysql.md

@@ -36,7 +36,6 @@ Dump the database schema. Argument is the database name.
 [create a soft backup of the database]
 mysql.dump: example_app
 path: /tmp/example_app.sql
-
 ```
 
 ### mysql.exists
@@ -46,10 +45,8 @@ Determine if a database exists. Argument is the database name.
 ```ini
 [determine if the database exists]
 mysql.exists: example_app
-
 ```
 
-
 ### mysql.grant
 
 Grant privileges to a user.
@@ -61,7 +58,6 @@ Grant privileges to a user.
 [grant select privileges to bob]
 mysql.grant: bob
 privileges: select
-
 ```
 
 ### mysql.user

help/en/docs/usage/packages.md

@@ -0,0 +1,44 @@
+# Packages
+
+Summary: Work with system packages.
+
+## Available Commands
+
+### install
+
+Install a package.
+
+```ini
+[install vim]
+install: vim
+sudo: yes
+```
+
+### uninstall
+
+Uninstall a package.
+
+```ini
+[uninstall vim]
+uninstall: vim
+sudo: yes
+```
+
+### update
+
+Update package information.
+
+```ini
+[update package info]
+update:
+sudo: yes
+```
+
+### upgrade
+
+Upgrade system packages.
+
+```ini
+upgrade:
+sudo: yes
+```

help/en/docs/usage/pgsql.md

@@ -18,7 +18,6 @@ Options provided in the steps file are automatically converted to command line s
 pgsql.dump: example_app
 schema_only: yes
 path: /tmp/example_app.sql
-
 ```
 
 `schema_only` becomes "--schema-only".
@@ -43,7 +42,6 @@ Drop a database. Argument is the database name.
 ```ini
 [drop the testing database]
 pgsql.drop: testing_example_app
-
 ```
 
 ### pgsql.dump
@@ -57,7 +55,6 @@ Dump the database schema. Argument is the database name.
 pgsql.dump: example_app
 column_inserts: yes
 path: /tmp/example_app.sql
-
 ```
 
 ### pgsql.exists
@@ -67,7 +64,6 @@ Determine if a database exists. Argument is the database name.
 ```ini
 [determine if the database exists]
 pgsql.exists: example_app
-
 ```
 
 ### pgsql.grant
@@ -88,7 +84,6 @@ pgsql.grant: bob
 database: example_app
 privileges: select
 schema: public
-
 ```
 
 ### pgsql.user

help/en/docs/usage/php.md

@@ -11,5 +11,4 @@ Enable a PHP module. Argument is the module name.
 ```ini
 [enable postgres for PHP]
 php.module: pdo_pgsql
-
 ```

help/en/docs/usage/posix.md

@@ -32,7 +32,6 @@ Create an archive (tarball). Argument is the target file or directory.
 archive: /path/to/file_or_directory
 file_name: testing.tgz
 to: /tmp
-
 ```
 
 ### certbot
@@ -48,7 +47,6 @@ Use Let's Encrypt (certbot) to acquire an SSL certificate. Argument is the domai
 [get an SSL cert]
 ssl: example.app
 email: webmaster@example.app
-
 ```
 
 ### copy
@@ -63,7 +61,6 @@ Copy a file or directory. First argument is the target file/directory. Second ar
 copy: /path/to/directory /path/to/new_directory
 overwrite: yes
 recursive: yes
-
 ```
 
 ### dir
@@ -82,7 +79,6 @@ group: www-data
 mode: 755
 owner: deploy
 recursive: yes
-
 ```
 
 ### extract
@@ -98,7 +94,6 @@ Extract an archive (tarball). Argument is the path to the archive file.
 ```ini
 [extract an archive]
 extract: /path/to/archive.tgz
-
 ```
 
 ### link
@@ -114,7 +109,6 @@ link: /path/to/project/releases/1.0
 cd: /path/to/project
 force: yes
 target: current
-
 ```
 
 ### move
@@ -124,7 +118,6 @@ Move a file or directory. First argument is the target. Second argument is the d
 ```ini
 [move a file]
 move: /path/to/file.txt /new/path/to/file.txt
-
 ```
 
 ### perms
@@ -143,7 +136,6 @@ group: www-data
 mode: 775
 owner: deploy
 recursive: yes
-
 ```
 
 ### push
@@ -167,7 +159,6 @@ push: /path/to/project /path/on/server
 key_file: ~/.ssh/example_app
 host: example.app
 user: deploy
-
 ```
 
 ### remove
@@ -181,7 +172,7 @@ Remove a file or directory. Argument is the path.
 [remove a directory]
 remove: /path/to/directory
 force: yes
-recusrive: yes
+recursive: yes
 ```
 
 ### replace
@@ -214,7 +205,6 @@ Copy a file to a remote server. First argument is the local file name. Second ar
 scopy: /path/to/local.txt path/to/remove.txt
 host: example.app
 user: deploy
-
 ```
 
 ### sync
@@ -229,7 +219,6 @@ Sync (rsync) local files and directories. First argument is the target. Second a
 ```ini
 [syncrhonize files on the local machine]
 sync: /path/to/project /path/to/sync/directory
-
 ```
 
 ### touch
@@ -260,5 +249,4 @@ Write to a file. Argument is the path.
 [replace an existing file]
 write: /path/to/file.txt
 content: This whole file has been replaced.
-
 ```

help/en/docs/usage/python.md

@@ -34,7 +34,6 @@ Install packages from a pip file.
 pip_file: deploy/packages/testing.pip
 cd: path/to/project
 venv: python
-
 ```
 
 ### virtualenv
@@ -45,5 +44,4 @@ Create a python virtual environment. Argument is the environment name.
 [create the virtual environment]
 virtualenv: python
 cd: /path/to/project
-
 ```

help/en/docs/usage/system.md

@@ -0,0 +1,60 @@
+# System
+
+Summary: Work with the system.
+
+## Available Commands
+
+### reboot
+
+Reboot the system.
+
+```ini
+[reboot the system]
+reboot:
+sudo: yes
+```
+
+### reload
+
+Reload a service.
+
+```ini
+[reload postgres]
+reload: postgresql
+```
+
+### restart
+
+Restart a service:
+
+```ini
+[restart postgres]
+restart: postgresql
+```
+
+### run
+
+Run any shell command.
+
+```ini
+[run a useless listing command]
+run: "ls -ls"
+```
+
+### start
+
+Start a service:
+
+```ini
+[start postgres]
+start: postgresql
+```
+
+### stop
+
+Stop a service:
+
+```ini
+[stop postgres]
+stop: postgresql
+```

help/en/docs/usage/ubuntu.md

@@ -2,7 +2,15 @@
 
 ## Available Commands
 
-The `ubuntu` profile incorporates commands from [Django](../commands/django.md), [messages](../commands/messages.md), [MySQL](../commands/mysql.md), [PHP](../commands/php.md), [POSIX](../commands/posix.md), [Postgres](../commands/pgsql.md), and [Python](../commands/python.md). 
+The `ubuntu` profile incorporates commands from
+
+- [Django](../commands/django.md)
+- [messages](../commands/messages.md)
+- [MySQL](../commands/mysql.md)
+- [PHP](../commands/php.md)
+- [POSIX](../commands/posix.md)
+- [Postgres](../commands/pgsql.md)
+- [Python](../commands/python.md)
 
 ### apache
 

help/en/docs/usage/users.md

@@ -0,0 +1,41 @@
+# Users
+
+Summary: Work with system users and groups.
+
+## Available Commands
+
+### group
+
+NOT YET IMPLEMENTED.
+
+### user
+
+Add or remove a user.
+
+Adding a user:
+
+```ini
+[create bob's user account]
+user: bob
+groups: sudo
+sudo: yes
+```
+
+To override the home directory:
+
+```ini
+[create the deploy user]
+user: deploy
+groups: sudo, www-data
+home: /var/www/example_app
+sudo: yes
+```
+
+Removing a user:
+
+```ini
+[remove bob's user account because he's screwing up the system]
+user: bob
+op: remove
+sudo: yes
+```

help/en/mkdocs.yml

@@ -22,15 +22,17 @@ nav:
       - Post a Message to Twist: how-to/post-message-twist.md
       - Use Script Tease with Common Kit: how-to/use-with-commonkit.md
   - Usage:
-      - CentOS: usage/centos.md
+      - Apache: usage/apache.md
       - Django: usage/django.md
       - Messages: usage/messages.md
       - MySQL: usage/mysql.md
       - PHP: usage/php.md
+      - Packages: usage/packages.md
       - Postgres: usage/pgsql.md
       - POSIX: usage/posix.md
       - Python: usage/python.md
-      - Ubuntu: usage/ubuntu.md
+      - System: usage/system.md
+      - Users: usage/users.md
   - CLI: cli.md
 repo_name: Git Traction
 repo_url: https://gittraction.com/diff6/python-scripttease

scripttease/lib/commands/posix.py

@@ -741,6 +741,7 @@ POSIX_MAPPINGS = {
     'move': move,
     'perms': perms,
     'prompt': prompt,
+    'push': rsync,
     'remove': remove,
     'replace': replace,
     'run': run,