Document some of the common scripts

This commit adds some documentation around the scripts that developers
will commonly encounter when working with os-a-d. It is intentionally
high level, so that only major modifications should require changing the
docs.

Change-Id: I6d8f72b418e041a956a3267bfee30d563bf35e34
Co-Authored-By: Matt Kassawara <mkassawara@gmail.com>
Implements: blueprint developer-docs

doc/source/index.rst

@@ -20,6 +20,7 @@ Contents:
    playbooks
    install-guide/index
    extending
+   scripts
 
 
 Indices and tables

doc/source/scripts.rst

@@ -0,0 +1,92 @@
+OpenStack Ansible Deployment Scripts
+====================================
+
+The repository contains several helper scripts to manage gate jobs,
+install base requirements, and update repository information. Invoke
+these scripts from the top-level directory of the repository. For
+example:
+
+.. code:: bash
+
+   $ scripts/<script_name>.sh
+
+Bootstrapping
+^^^^^^^^^^^^^
+
+bootstrap-aio.sh
+----------------
+
+The ``bootstrap-aio.sh`` script prepares a host for an *all-in-one* (AIO)
+deployment for the purposes of development and gating. Create the necessary
+partitions, directories, and configurations. Configurable via environment
+variables to work with Jenkins.
+
+bootstrap-ansible.sh
+--------------------
+
+The ``bootstrap-ansible.sh`` script installs Ansible including core and extras
+module repositories and Galaxy roles.
+
+Configurable environment variables:
+
+* ``ANSIBLE_GIT_RELEASE`` - Version of Ansible to install.
+* ``ANSIBLE_ROLE_FILE`` - Galaxy roles to install. Defaults to
+  contents of ``ansible-role-requirements.yml`` file.
+
+The script also creates the ``openstack-ansible`` wrapper tool that provides
+the variable files to match ``/etc/openstack_deploy/user_*.yml`` as
+arguments to ``ansible-playbook`` as a convenience.
+
+Gating
+^^^^^^
+
+gate-check-commit.sh
+--------------------
+
+The ``gate-check-commit.sh`` script executes a suite of tests necessary for
+each commit to the repository. By default, the script runs the bootstrap
+scripts, builds an *all-in-one* deployment of OSAD, and runs various Tempest
+tests on it.
+
+Configurable environment variables:
+
+* ``BOOTSTRAP_AIO`` - Boolean (yes/no) to run AIO bootstrap script. Defaults
+  to ``yes``.
+* ``BOOTSTRAP_AIO`` - Boolean (yes/no) to run Ansible bootstrip script.
+  Defaults to ``yes``.
+* ``RUN_TEMPEST`` - Boolean (yes/no) to run Tempest tests. Defaults to
+  ``yes``.
+
+gate-check-docs.sh
+------------------
+
+The ``gate-check-docs.sh`` script invokes Sphinx to build the HTML
+documentation from RST source.
+
+gate-check-lint.sh
+------------------
+
+The ``gate-check-lint.sh`` script executes a suite of tests necessary for each
+commit to the repository to verify correct YAML and Python syntax.
+
+All files that begin with a Python shebang pass through *flake8* which ignores
+the following rules due to Ansible conventions:
+
+ * F403 - 'from ansible.module_utils.basic import \*'
+ * H303 - No wildcard imports
+
+Ansible playbooks pass through ``ansible-playbook --syntax-check``
+and ``ansible-lint``.
+
+run-tempest.sh
+--------------
+
+The ``run-tempest.sh`` script runs Tempest tests from the first utility
+container. The ``check-gate-commit.sh`` script usually invokes this
+script after it completes the OSAD deployment.
+
+Configurable environment variables:
+
+* ``TEMPEST_SCRIPT_PARAMETERS`` - Defines tests to run. Values are passed to
+  ``openstack_tempest_gate.sh`` script, defined in the ``os_tempest`` role.
+  Defaults to ``scenario heat_api cinder_backup``.