Converted existing markdown documentation to RST format.

Removed MD versions.
Moved examples directory up one under repo root
Moved RST files under docs/how-to-use

Change-Id: I4137b8591e4ae63e40674a7f5f8243d928efee0c
Signed-off-by: spisarski <s.pisarski@cablelabs.com>

22 files changed, 987 insertions, 1189 deletions

diff --git a/docs/APITests.md b/docs/APITests.md
deleted file mode 100644
index 8376203..0000000
--- a/docs/APITests.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# SNAPS OpenStack API Testing
-
-Tests designated as component tests extend the snaps.openstack.tests.OSComponentTestCase class and must be exercised
-with OpenStack credentials for all as well as an external network for many. When leveraging the unit_test_suite.py
-application, the -e argument and -n arguments will suffice. When attempting to execute these tests within your IDE
-of choice (tested on IntelliJ), you will need to edit the [repo_dir]/snaps/openstack/tests/conf/os_env.yaml file as well
-as ensuring that your run configuration's working directory is set to [repo_dir]/snaps.
-
-# The Test Classes
-
-## glance_utils_tests.py - GlanceSmokeTests
-Ensures that a Glance client can be obtained as well as the proper exceptions thrown with the wrong credentials.
-
-## keystone_utils_tests.py - KeystoneSmokeTests
-Ensures that a Keystone client can be obtained as well as the proper exceptions thrown with the wrong credentials.
-
-## neutron_utils_tests.py - NeutronSmokeTests
-Ensures that a Neutron client can be obtained as well as the proper exceptions thrown with the wrong credentials.
-
-## nova_utils_tests.py - NovaSmokeTests
-Ensures that a Nova client can be obtained as well as the proper exceptions thrown with the wrong credentials.
-
-## keystone_utils_tests.py - KeystoneUtilsTests
-| Test Name 	| Keystone API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_user_minimal|2 & 3|Tests the creation of a user with minimal configuration settings via the utility functions|
-|test_create_project_minimal|2 & 3|Tests the creation of a project with minimal configuration settings via the utility functions|
-
-## create_user_tests.py - CreateUserSuccessTests
-| Test Name 	| Keystone API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_user|2 & 3|Tests the creation of a user via the OpenStackUser class|
-|test_create_user_2x|2 & 3|Tests the creation of a user a second time via the OpenStackUser class to ensure it is only created once|
-|test_create_delete_user|2 & 3|Tests the creation and deletion of a user via the OpenStackUser class to ensure that clean() will not raise an exception|
-
-## create_project_tests.py - CreateProjectSuccessTests
-| Test Name 	| Keystone API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_project|2 & 3|Tests the creation of a project via the OpenStackProject class|
-|test_create_project_2x|2 & 3|Tests the creation of a project a second time via the OpenStackProject class to ensure it is only created once|
-|test_create_delete_project|2 & 3|Tests the creation and deletion of a project via the OpenStackProject class to ensure that clean() will not raise an exception|
-
-## create_project_tests.py - CreateProjectUserTests
-| Test Name 	| Keystone API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_project_sec_grp_one_user|2 & 3|Tests the creation of an OpenStack object to a project with a new users and to create a security group|
-|test_create_project_sec_grp_two_users|2 & 3|Tests the creation of an OpenStack object to a project with two new users and to create a security group under each|
-
-## glance_utils_tests.py - GlanceUtilsTests
-| Test Name 	| Glance API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_image_minimal_url|1|Tests the glance_utils.create_image() function with a URL|
-|test_create_image_minimal_file|1|Tests the glance_utils.create_image() function with a file|
-
-## neutron_utils_tests.py - NeutronUtilsNetworkTests
-| Test Name 	| Neutron API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_network|2|Ensures neutron_utils.create_network() properly creates a network|
-|test_create_network_empty_name|2|Ensures neutron_utils.create_network() raises an exception when the network name is an empty string|
-|test_create_network_null_name|2|Ensures neutron_utils.create_network() raises an exception when the network name is None|
-
-## neutron_utils_tests.py - NeutronUtilsSubnetTests
-| Test Name 	| Neutron API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_subnet|2|Ensures neutron_utils.create_subnet() can properly create an OpenStack subnet object|
-|test_create_subnet_null_name|2|Ensures neutron_utils.create_subnet() raises an exception when the subnet name is None|
-|test_create_subnet_empty_name|2|Ensures neutron_utils.create_subnet() raises an exception when the subnet name is an empty string|
-|test_create_subnet_null_cidr|2|Ensures neutron_utils.create_subnet() raises an exception when the subnet CIDR is None|
-|test_create_subnet_empty_cidr|2|Ensures neutron_utils.create_subnet() raises an exception when the subnet CIDR is an empty string|
-
-## neutron_utils_tests.py - NeutronUtilsRouterTests
-| Test Name 	| Neutron API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_router_simple|2|Ensures neutron_utils.create_router() can properly create a simple OpenStack router object|
-|test_create_router_with_public_interface|2|Ensures neutron_utils.create_router() can properly create an OpenStack router object with an interface to the external network|
-|test_create_router_empty_name|2|Ensures neutron_utils.create_router() raises an exception when the name is an empty string|
-|test_create_router_null_name|2|Ensures neutron_utils.create_router() raises an exception when the name is None|
-|test_add_interface_router|2|Ensures neutron_utils.add_interface_router() properly adds an interface to another subnet|
-|test_add_interface_router_null_router|2|Ensures neutron_utils.add_interface_router() raises an exception when the router object is None|
-|test_add_interface_router_null_subnet|2|Ensures neutron_utils.add_interface_router() raises an exception when the subnet object is None|
-|test_create_port|2|Ensures neutron_utils.create_port() can properly create an OpenStack port object|
-|test_create_port_empty_name|2|Ensures neutron_utils.create_port() raises an exception when the port name is an empty string|
-|test_create_port_null_name|2|Ensures neutron_utils.create_port() raises an exception when the port name is None|
-|test_create_port_null_network_object|2|Ensures neutron_utils.create_port() raises an exception when the network object is None|
-|test_create_port_null_ip|2|Ensures neutron_utils.create_port() raises an exception when the assigned IP value is None|
-|test_create_port_invalid_ip|2|Ensures neutron_utils.create_port() raises an exception when the assigned IP value is invalid|
-|test_create_port_invalid_ip_to_subnet|2|Ensures neutron_utils.create_port() raises an exception when the assigned IP value is not part of CIDR|
-
-## neutron_utils_tests.py - NeutronUtilsSecurityGroupTests
-| Test Name 	| Neutron API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_delete_simple_sec_grp|2|Ensures that a security group can be created (neutron_utils.create_security_group() and deleted via neutron_utils.delete_security_group()|
-|test_create_sec_grp_no_name|2|Ensures that neutron_utils.create_security_group() raises an exception when attempting to create a security group without a name|
-|test_create_sec_grp_no_rules|2|Ensures that neutron_utils.create_security_group() can create a security group without any rules|
-|test_create_sec_grp_one_rule|2|Ensures that neutron_utils.create_security_group_rule() can add a rule to a security group|
-
-## nova_utils_tests.py - NovaUtilsKeypairTests
-| Test Name 	| Nova API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_keypair|2|Ensures that a keypair can be properly created via nova_utils.upload_keypair() with a public_key object|
-|test_create_delete_keypair|2|Ensures that a keypair can be properly deleted via nova_utils.delete_keypair()|
-|test_create_key_from_file|2|Ensures that a keypair can be properly created via nova_utils.upload_keypair_file()|
-|test_floating_ips|2|Ensures that a floating IP can be properly created via nova_utils.create_floating_ip() [note: this test should be moved to a new class]|
-
-## nova_utils_tests.py - NovaUtilsFlavorTests
-| Test Name 	| Nova API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_flavor|2|Ensures that a flavor can be properly created via nova_utils.create_flavor()|
-|test_create_delete_flavor|2|Ensures that a flavor can be properly deleted via nova_utils.delete_flavor()|
-
-## create_flavor_tests.py - CreateFlavorTests
-| Test Name 	| Nova API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_create_flavor|2|Ensures that the OpenStackFlavor class's create() method creates an OpenStack flavor object|
-|test_create_flavor_existing|2|Ensures that the OpenStackFlavor class's create() will not create a flavor with the same name more than once|
-|test_create_clean_flavor|2|Ensures that the OpenStackFlavor class's clean() method will delete the flavor object|
-|test_create_delete_flavor|2|Ensures that the OpenStackFlavor class's clean() method will not raise an exception when called and the object no longer exists|
diff --git a/docs/IntegrationTests.md b/docs/IntegrationTests.md
deleted file mode 100644
index 0433e5a..0000000
--- a/docs/IntegrationTests.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# SNAPS OpenStack Integration Testing
-
-These tests are ones designed to be run within their own dynamically created project along with a newly generated user
-account and generally require other OpenStack object creators.
-
-# The Test Classes
-
-## create_security_group_tests.py - CreateSecurityGroupTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_group_without_rules|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup class can create a security group without any rules|
-|test_create_delete_group|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup class clean() method will not raise an exception should the group be deleted by some other process|
-|test_create_group_with_one_simple_rule|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup class can create a security group with a single rule|
-|test_create_group_with_several_rules|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup class can create a security group with several rules|
-|test_add_rule|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup#add_rule() method properly creates and associates the new rule|
-|test_remove_rule_by_id|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup#remove_rule() method properly deletes and disassociates the old rule via its ID|
-|test_remove_rule_by_setting|Keystone 2 & 3 Neutron 2|Ensures the OpenStackSecurityGroup#remove_rule() method properly deletes and disassociates the old rule via its setting object|
-
-## create_image_tests.py - CreateImageSuccessTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_image_clean_url|Glance 1|Ensures the OpenStackImage class can create an image from a download URL location|
-|test_create_image_clean_file|Glance 1|Ensures the OpenStackImage class can create an image from a locally sourced image file|
-|test_create_delete_image|Glance 1|Ensures the OpenStackImage.clean() method deletes an image and does not raise an exception on subsequent calls to the clean() method|
-|test_create_same_image|Glance 1|Ensures the OpenStackImage.create() method does not create another image when one already exists with the same name|
-
-## create_image_tests.py - CreateImageNegativeTests
-| Test Name 	| Glance API Version 	| Description 	|
-|---	|:-:	|---	|
-|test_none_image_name|1|Ensures OpenStackImage.create() results in an Exception being raised when the ImageSettings.name attribute has not been set|
-|test_bad_image_url|1|Ensures OpenStackImage.create() results in an Exception being raised when the download URL is invalid|
-|test_bad_image_file|1|Ensures OpenStackImage.create() results in an Exception being raised when the image file does not exist|
-|test_none_proj_name|1|Ensures OpenStackImage.create() results in an Exception being raised when credentials project name is None|
-|test_none_auth_url|1|Ensures OpenStackImage.create() results in an Exception being raised when credentials URL is None|
-|test_none_password|1|Ensures OpenStackImage.create() results in an Exception being raised when credentials password is None|
-|test_none_user|1|Ensures OpenStackImage.create() results in an Exception being raised when credentials user is None|
-
-## create_keypairs_tests.py - CreateKeypairsTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_keypair_only|Nova 2|Ensures that a keypair object can be created simply by only configuring a name|
-|test_create_delete_keypair|Nova 2|Ensures that a keypair object is deleted via OpenStackKeypair.clean() and subsequent calls do not result in exceptions|
-|test_create_keypair_save_pub_only|Nova 2|Ensures that a keypair object can be created when the only the public key is cached to disk|
-|test_create_keypair_save_both|Nova 2|Ensures that a keypair object can be created when both the public and private keys are cached to disk|
-|test_create_keypair_from_file|Nova 2|Ensures that a keypair object can be created with an existing public key file|
-
-## create_network_tests.py - CreateNetworkSuccessTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_network_without_router|Neutron 2|Ensures that a network can be created via the OpenStackNetwork class without any routers|
-|test_create_delete_network|Neutron 2|Ensures that a router can be deleted via the OpenStackNetwork.clean() method|
-|test_create_network_with_router|Neutron 2|Ensures that a network can be created via the OpenStackNetwork class with a router|
-|test_create_networks_same_name|Neutron 2|Ensures that the OpenStackNetwork.create() method will not create a network with the same name|
-
-## create_router_tests.py - CreateRouterSuccessTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_router_vanilla|Neutron 2|Ensures that a router can be created via the OpenStackRouter class with minimal settings|
-|test_create_delete_router|Neutron 2|Ensures that a router can be deleted via the OpenStackRouter.clean() method|
-|test_create_router_admin_state_false|Neutron 2|Ensures that a router can created with admin_state_up = False|
-|test_create_router_admin_state_True|Neutron 2|Ensures that a router can created with admin_state_up = True|
-|test_create_router_private_network|Neutron 2|Ensures that a router port can be created against a private network|
-|test_create_router_external_network|Neutron 2|Ensures that a router can be created that is connected to both external and private internal networks|
-
-## create_router_tests.py - CreateRouterNegativeTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_router_noname|Neutron 2|Ensures that an exception is raised when attempting to create a router without a name|
-|test_create_router_invalid_gateway_name|Neutron 2|Ensures that an exception is raised when attempting to create a router to an external network that does not exist|
-
-## create_instance_tests.py - CreateInstanceSimpleTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_create_delete_instance|Nova and Neutron 2|Ensures that the OpenStackVmInstance.clean() method deletes the instance|
-
-## create_instance_tests.py - SimpleHealthCheck
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_check_vm_ip_dhcp|Nova and Neutron 2|Tests the creation of an OpenStack instance with a single port and it's assigned IP address|
-
-## create_instance_tests.py - CreateInstanceSingleNetworkTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_single_port_static|Nova and Neutron 2|Ensures that an instance with a single port/NIC with a static IP can be created|
-|test_ssh_client_fip_before_active|Nova and Neutron 2|Ensures that an instance can be reached over SSH when the floating IP is assigned prior to the VM becoming ACTIVE|
-|test_ssh_client_fip_after_active|Nova and Neutron 2|Ensures that an instance can be reached over SSH when the floating IP is assigned after to the VM becoming ACTIVE|
-
-## create_instance_tests.py - CreateInstancePortManipulationTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_set_custom_valid_ip_one_subnet|Nova and Neutron 2|Ensures that an instance's can have a valid static IP is properly assigned|
-|test_set_custom_invalid_ip_one_subnet|Nova and Neutron 2|Ensures that an instance's port with an invalid static IP raises an exception|
-|test_set_custom_valid_mac|Nova and Neutron 2|Ensures that an instance's port can have a valid MAC address properly assigned|
-|test_set_custom_invalid_mac|Nova and Neutron 2|Ensures that an instance's port with an invalid MAC address raises and exception|
-|test_set_custom_mac_and_ip|Nova and Neutron 2|Ensures that an instance's port with a valid static IP and MAC are properly assigned|
-|test_set_allowed_address_pairs|Nova and Neutron 2|Ensures the configured allowed_address_pairs is properly set on a VMs port|
-|test_set_allowed_address_pairs_bad_mac|Nova and Neutron 2|Ensures the port cannot be created when a bad MAC address format is used in the allowed_address_pairs port attribute|
-|test_set_allowed_address_pairs_bad_ip|Nova and Neutron 2|Ensures the port cannot be created when a bad IP address format is used in the allowed_address_pairs port attribute|
-
-## create_instance_tests.py - CreateInstanceOnComputeHost
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_deploy_vm_to_each_compute_node|Nova and Neutron 2|Tests to ensure that one can fire up an instance on each active compute node|
-
-## create_instance_tests.py - CreateInstancePubPrivNetTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_dual_ports_dhcp|Nova and Neutron 2|Ensures that a VM with two ports/NICs can have its second NIC configured via SSH/Ansible after startup|
-
-## create_instance_tests.py - InstanceSecurityGroupTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_add_security_group|Nova and Neutron 2|Ensures that a VM instance can have security group added to it while its running|
-|test_add_invalid_security_group|Nova and Neutron 2|Ensures that a VM instance does not accept the addition of a security group that no longer exists|
-|test_remove_security_group|Nova and Neutron 2|Ensures that a VM instance accepts the removal of a security group|
-|test_remove_security_group_never_added|Nova and Neutron 2|Ensures that a VM instance does not accept the removal of a security group that was never added in the first place|
-|test_add_same_security_group|Nova and Neutron 2|Ensures that a VM instance does not add a security group that has already been added to the instance|
-
-## ansible_utils_tests.py - AnsibleProvisioningTests
-| Test Name 	| API Versions 	| Description 	|
-|---	|:-:	|---	|
-|test_apply_simple_playbook|Nova and Neutron 2|Ensures that an instance assigned with a floating IP will apply a simple Ansible playbook|
-|test_apply_template_playbook|Nova and Neutron 2|Ensures that an instance assigned with a floating IP will apply a Ansible playbook containing Jinga2 substitution values|
diff --git a/docs/Testing.md b/docs/Testing.md
deleted file mode 100644
index 7fdbbf2..0000000
--- a/docs/Testing.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Running Unit Test Suite
-These tests are written in Python and require an that it is setup before running the tests.
-See [install directions](index.md) for Python installation instructions.
-
-## Start by cloning the snaps-provisioning repository
-
-  ```
-  git clone https://gerrit.cablelabs.com/snaps-provisioning
-  ```
-
-## Install Library
-
-  ```
-  pip install -e <path to repo>/
-  ```
-
-
-## Execute the tests
-
-  ```
-  cd <path to repo>
-  python snaps/unit_test_suite.py -e [path to RC file] -n [external network name]
-  ```
-    * All Supported Arguments
-      * -e [required - The path to the OpenStack RC file]
-      * -n [required - The name of the external network to use for routers and floating IPs]
-      * -p [optional - the proxy settings if required. Format <host>:<port>
-      * -s [optional - the proxy command used for SSH connections]
-      * -l [(default INFO) The log level]
-      * -k [optional - When set, tests project and user creation. Use only if host running tests has access to the cloud's admin network]
-      * -f [optional - When set, will not execute tests requiring Floating IPS]
-      * -u [optional - When set, the unit tests will be executed]
-
-# Test descriptions
-## [Unit Testing] (UnitTests.md) - Tests that do not require a connection to OpenStack
-## [OpenStack API Tests] (APITests.md) - Tests many individual OpenStack API calls
-## [Integration Tests] (IntegrationTests.md) - Tests OpenStack object creation in a context. These tests will be run within a custom project as a specific user.
diff --git a/docs/UnitTests.md b/docs/UnitTests.md
deleted file mode 100644
index 59fc2d9..0000000
--- a/docs/UnitTests.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# SNAPS Unit Testing
-
-Tests designated as Unit tests extend the unittest.TestCase class and can be exercised without any external resources
-other than the filesystem. Most of these tests simply ensure that the configuration settings classes check their
-constructor arguments properly.
-
-# The Test Classes
-
-## FileUtilsTests
-* testFileIsDirectory - ensures that the expected path is a directory
-* testFileNotExist - ensures that a file that does not exist returns False
-* testFileExists - ensures that a file that does exist returns True
-* testDownloadBadUrl - ensures that an Exception is thrown when attempting to download a file with a bad URL
-* testCirrosImageDownload - ensures that the Cirros image can be downloaded
-* testReadOSEnvFile - ensures that an OpenStack RC file can be properly parsed
-
-## SecurityGroupRuleSettingsUnitTests
-Ensures that all required members are included when constructing a SecurityGroupRuleSettings object
-
-## SecurityGroupSettingsUnitTests
-Ensures that all required members are included when constructing a SecuirtyGroupSettings object
-
-## ImageSettingsUnitTests
-Ensures that all required members are included when constructing a ImageSettings object
-
-## KeypairSettingsUnitTests
-Ensures that all required members are included when constructing a KeypairSettings object
-
-## UserSettingsUnitTests
-Ensures that all required members are included when constructing a UserSettings object
-
-## ProjectSettingsUnitTests
-Ensures that all required members are included when constructing a ProjectSettings object
-
-## NetworkSettingsUnitTests
-Ensures that all required members are included when constructing a NetworkSettings object
-
-## SubnetSettingsUnitTests
-Ensures that all required members are included when constructing a SubnetSettings object
-
-## PortSettingsUnitTests
-Ensures that all required members are included when constructing a PortSettings object
-
-## FloatingIpSettingsUnitTests
-Ensures that all required members are included when constructing a FloatingIpSettings object
-
-## VmInstanceSettingsUnitTests
-Ensures that all required members are included when constructing a VmInstanceSettings object
diff --git a/docs/VirtEnvDeploy.md b/docs/VirtEnvDeploy.md
deleted file mode 100644
index decec94..0000000
--- a/docs/VirtEnvDeploy.md
+++ /dev/null
@@ -1,158 +0,0 @@
-# Overview
-The main purpose of this project is to enable one to describe a virtual environment in a YAML file and enable the
-user to deploy it to an OpenStack cloud in a repeatable manner. There are also options to un-deploy that same
-environment by leveraging the original YAML file.
-
-# To deploy/clean virtual environments
-  * Clone Repository
-    * git clone https://gerrit.cablelabs.com/snaps-provisioning
-  * Install Library
-    * pip install -e <path to repo>/
-  * Deploy
-    * cd <path to repo>
-    * python snaps/deploy_venv.py -e <path to deployment configuration YAML file> -d
-    * Working example:
-
-```
-python deploy_venv.py -e <path to repo>/docs/examples/complex-network/deploy-complex-network.yaml -d
-```
-  * Clean
-    * python deploy_venv.py -e <path to deployment configuration YAML file> -c
-    * Working example (cleanup of a previously deployed virtual environment where the VM has Yardstick installed):
-
-```
-python deploy_venv.py -e <path to repo>/docs/examples/complex-network/deploy-complex-network.yaml -c
-```
-      
-# Environment Configuration YAML File
-The configuration file used to deploy and provision a virtual environment has been designed to describe the required
-images, networks, SSH public and private keys, associated VMs, as well as any required post deployment provisioning
-tasks. A fully formed sample can be found in the ./provisioning/ansible/unimgr/deploy-unimgr.yaml that can be dowloaded
-from here.
-
-*** Please note that many of the more esoteric optional supported attributes still have not been fully tested. ***
-*** Some of the nested bullets are being hidden by GitLabs, please see doc/VirtEnvDeploy.md.***
-
-  * openstack: the top level tag that denotes configuration for the OpenStack components
-    * connection: - contains the credentials and endpoints required to connect with OpenStack
-      * username: - the project's user (required)
-      * password: - the tentant's user password (required)
-      * auth_url: - the URL to the OpenStack APIs (required)
-      * project_name: - the name of the OpenStack project for the user (required)
-      * http_proxy: - the {{ host }}:{{ port }} of the proxy server the HTTPPhotoman01(optional)
-    * images: - describes each image
-      * image:
-        * name: The unique image name. If the name already exists for your project, a new one will not be created (required)
-        * format: The format type of the image i.e. qcow2 (required)
-        * download_url: The HTTP download location of the image file (required)
-        * nic_config_pb_loc: The file location relative to the CWD (python directory) to the Ansible Playbook used to configure VMs with more than one port. VMs get their first NIC configured for free while subsequent ones are not. This value/script will only be leveraged when necessary. Centos has been supported with "provisioning/ansible/centos-network-setup/configure_host.yml".
-    * networks:
-      * network:
-        * name: The name of the network to be created. If one already exists, a new one will not be created (required)
-        * admin_state_up: T|F (default True)
-        * shared: (optional)
-        * project_name: Name of the project who owns the network. Note: only administrative users can specify projects other than their own (optional)
-        * external: T|F whether or not network is external (default False)
-        * network_type: The type of network to create. (optional)
-        * subnets:
-          * subnet:
-            * name: The name of the network to be created. If one already exists, a new one will not be created. Note: although OpenStack allows for multiple subnets to be applied to any given network, we have not included support as our current use cases does not utilize this functionality (required)
-            * cidr: The subnet mask value (required)
-            * dns_nameservers: A list of IP values used for DNS resolution (default: 8.8.8.8)
-            * ip_version: 4|6 (default: 4)
-            * project_name: Name of the project who owns the network. Note: only administrative users can specify projects other than their own (optional)
-            * start: The start address for allocation_pools (optional)
-            * end: The ending address for allocation_pools (optional)
-            * gateway_ip: The IP address to the gateway (optional)
-            * enable_dhcp: T|F (optional)
-            * dns_nameservers: List of DNS server IPs
-            * host_routes: A list of host route dictionaries (optional) i.e.:
-      ```yaml
-           "host_routes":[
-           {
-           "destination":"0.0.0.0/0",
-           "nexthop":"123.456.78.9"
-           },
-           {
-           "destination":"192.168.0.0/24",
-           "nexthop":"192.168.0.1"
-           }
-           ]
-      ```
-            * destination: The destination for a static route (optional)
-            * nexthop: The next hop for the destination (optional)
-            * ipv6_ra_mode: Valid values: "dhcpv6-stateful", "dhcpv6-stateless", and "slaac" (optional)
-            * ipv6_address_mode: Valid values: "dhcpv6-stateful", "dhcpv6-stateless", and "slaac" (optional)
-      * routers:
-        * router:
-          * name: The name of the router to be created. If one already exists, a new one will not be created (required)
-          * project_name: Name of the project who owns the network. Note: only administrative users can specify projects other than their own (optional)
-          * internal_subnets: A list of subnet names on which the router will be placed (optional)
-          * external_gateway: A dictionary containing the external gateway parameters: "network_id", "enable_snat", "external_fixed_ips" (optional)
-          * interfaces: A list of port interfaces to create to other subnets (optional)
-            * port (Leverages the same class/structure as port objects on VM instances. See port definition below for a
-                    full accounting of the port attributes. The ones listed below are generally used for routers)
-                * name: The name given to the new port (must be unique for project) (required)
-                * network_name: The name of the new port's network (required)
-                * ip_addrs: A list of k/v pairs (optional)
-                  * subnet_name: the name of a subnet that is on the port's network
-                  * ip: An IP address of the associated subnet to assign to the new port (optional but generally required for router interfaces)
-      * keypairs:
-        * keypair:
-          * name: The name of the keypair to be created. If one already exists, a new one will not be created but simply loaded from its configured file location (required)
-          * public_filepath: The path to where the generated public key will be stored if it does not exist (optional but really required for provisioning purposes)
-          * private_filepath: The path to where the generated private key will be stored if it does not exist (optional but really required for provisioning purposes)
-      * instances:
-        * instance:
-        * name: The unique instance name for project. (required)
-        * flavor: Must be one of the preconfigured flavors (required)
-        * imageName: The name of the image to be used for deployment (required)
-        * keypair_name: The name of the keypair to attach to instance (optional but required for NIC configuration and Ansible provisioning)
-        * sudo_user: The name of a sudo_user that is attached to the keypair (optional but required for NIC configuration and Ansible provisioning)
-        * vm_boot_timeout: The number of seconds to block waiting for an instance to deploy and boot (default 900)
-        * vm_delete_timeout: The number of seconds to block waiting for an instance to be deleted (default 300)
-        * ssh_connect_timeout: The number of seconds to block waiting for an instance to achieve an SSH connection (default 120)
-        * ports: A list of port configurations (should contain at least one)
-          * port: Denotes the configuration of a NIC
-            * name: The unique port name for project (required)
-            * network_name: The name of the network to which the port is attached (required)
-            * ip_addrs: Static IP addresses to be added to the port by subnet (optional) 
-              * subnet_name: The name of the subnet
-              * ip: The assigned IP address (when null, OpenStack will assign an IP to the port)
-            * admin_state_up: T|F (default True)
-            * project_name: The name of the project who owns the network. Only administrative users can specify a the project ID other than their own (optional)
-            * mac_address: The desired MAC for the port (optional)
-            * fixed_ips: A dictionary that allows one to specify only a subnet ID, OpenStack Networking allocates an available IP from that subnet to the port. If you specify both a subnet ID and an IP address, OpenStack Networking tries to allocate the specified address to the port. (optional)
-            * seurity_groups: A list of security group IDs (optional)
-            * allowed_address_pairs: A dictionary containing a set of zero or more allowed address pairs. An address pair contains an IP address and MAC address. (optional)
-            * opt_value: The extra DHCP option value (optional)
-            * opt_name: The extra DHCP option name (optional)
-            * device_owner: The ID of the entity that uses this port. For example, a DHCP agent (optional)
-            * device_id: The ID of the device that uses this port. For example, a virtual server (optional)
-      * floating_ips: list of floating_ip configurations (optional)
-        * floating_ip:
-          * name: Must be unique for VM instance (required)
-          * port_name: The name of the port requiring access to the external network (required)
-          * subnet_name: The name of the subnet contains the IP address on the port on which to create the floating IP (optional)
-          * router_name: The name of the router connected to an external network used to attach the floating IP (required)
-          * provisioning: (True|False) Denotes whether or not this IP can be used for Ansible provisioning (default True)
-  * ansible: Each set of attributes below are contained in a list
-    * playbook_location: Full path or relative to the directory in which the deployment file resides (required)
-    * hosts: A list of hosts to which the playbook will be executed (required)
-    * variables: Should your Ansible scripts require any substitution values to be applied with Jinga2templates, the values defined here will be used to for substitution
-      * tag name = substitution variable names. For instance, for any file being pushed to the host being provisioned containing a value such as {{ foo }}, you must specify a tag name of "foo"
-        * vm_name:
-        * type: string|port|os_creds|vm-attr (note: will need to make changes to deploy_venv.py#__get_variable_value() for additional support)
-           * when type == string, an tag name "value" must exist and its value will be used for template substituion
-           * when type == port, custom code has been written to extract certain assigned values to the port:
-              * vm_name: must correspond to a VM's name as configured in this file
-              * port_name: The name of the port from which to extract the substitution values (required)
-              * port_value: The port value. Currently only supporting "mac_address" and "ip_address" (only the first)
-           * when type == os_creds, custom code has been written to extract the file's connection values:
-              * username: connection's user
-              * password: connection's password
-              * auth_url: connection's URL
-              * project_name: connection's project
-           * when type == vm-attr, custom code has been written to extract the following attributes from the vm:
-              * vm_name: must correspond to a VM's name as configured in this file
-              * value -> floating_ip: is currently the only vm-attr supported
\ No newline at end of file
diff --git a/docs/examples/complex-network/deploy-complex-network.yaml b/docs/examples/complex-network/deploy-complex-network.yaml
deleted file mode 100644
index 42559e8..0000000
--- a/docs/examples/complex-network/deploy-complex-network.yaml
+++ /dev/null
@@ -1,234 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-openstack:
-  connection:
-    # Note - when http_proxy is set, you must also configure ssh for proxy tunneling on your host.
-    username: admin
-    password: cable123
-    auth_url: http://10.197.103.50:5000/v2.0/
-    project_name: admin
-    http_proxy: localhost:3128
-  images:
-    - image:
-        name: centos-inst-test
-        format: qcow2
-        image_user: centos
-        download_url: http://cloud.centos.org/centos/7/images/CentOS-7-x86_64-GenericCloud.qcow2
-        nic_config_pb_loc: provisioning/ansible/centos-network-setup/playbooks/configure_host.yml
-    - image:
-        name: Ubuntu-14.04
-        format: qcow2
-        image_user: ubuntu
-        download_url: http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img
-        nic_config_pb_loc: provisioning/ansible/ubuntu-network-setup/playbooks/configure_host.yml
-  networks:
-    - network:
-        name: mgr-net
-        subnets:
-          - subnet:
-              name: mgr-subnet
-              cidr: 10.0.1.0/24
-              dns_nameservers: [8.8.8.8]
-          - subnet:
-              name: mgr-subnet-2
-              cidr: 10.0.2.0/24
-              dns_nameservers: [8.8.8.8]
-    - network:
-        name: site1-net
-        subnets:
-          - subnet:
-              name: site1-subnet
-              cidr: 192.168.0.0/24
-              gateway_ip: 192.168.0.1
-          - subnet:
-              name: site1-subnet-2
-              cidr: 192.168.1.0/24
-              gateway_ip: 192.168.1.1
-    - network:
-        name: site2-net
-        subnets:
-          - subnet:
-              name: site2-subnet
-              cidr: 192.169.0.0/24
-              gateway_ip: 192.169.0.1
-  routers:
-  # Note: Routers between internal networks not being used but put in here as an example on how to do that.
-    - router:
-        name: mgr-router
-        external_gateway: external
-        internal_subnets:
-          - mgr-subnet
-          - mgr-subnet-2
-        interfaces:
-          - port:
-              name: mgr-router-to-site1
-              network_name: site1-net
-              ip_addrs:
-                - subnet_name: site1-subnet
-                  ip: 192.168.0.10
-    - router:
-        name: site1-router
-        external_gateway: external
-        internal_subnets:
-          - site1-subnet
-    - router:
-        name: site2-router
-        external_gateway: external
-        internal_subnets:
-          - site2-subnet
-    - router:
-        name: site-to-site-router
-        interfaces:
-          - port:
-              name: site1-router-port
-              network_name: site1-net
-              ip_addrs:
-                - subnet_name: site1-subnet
-                  ip: 192.168.0.100
-          - port:
-              name: site2-router-port
-              network_name: site2-net
-              ip_addrs:
-                - subnet_name: site2-subnet
-                  ip: 192.169.0.100
-  keypairs:
-    - keypair:
-        name: cmplx-net-kp
-        public_filepath: /tmp/cmplx-net-kp.pub
-        private_filepath: /tmp/cmplx-net-kp
-  instances:
-    - instance:
-        name: mgr-app
-        flavor: m1.small
-        imageName: centos-inst-test
-        keypair_name: cmplx-net-kp
-        vm_boot_timeout: 600
-        vm_delete_timeout: 120
-        ssh_connect_timeout: 120
-        ports:
-          - port:
-              name: mgr-app-port
-              network_name: mgr-net
-              ip_addrs:
-                - subnet_name: mgr-subnet
-                  ip: 10.0.1.30
-                - subnet_name: mgr-subnet-2
-                  ip: 10.0.2.30
-        floating_ips:
-# TODO - Why is only one of these floating IPs not working and why does it vary which one?
-#          - floating_ip:
-#              name: fip1
-#              port_name: mgr-app-port
-#              subnet_name: mgr-subnet
-#              router_name: mgr-router
-#              provisioning: False
-          - floating_ip:
-              name: fip2
-              port_name: mgr-app-port
-              subnet_name: mgr-subnet-2
-              router_name: mgr-router
-    - instance:
-        name: site1-ovs
-        flavor: m1.small
-        imageName: centos-inst-test
-        keypair_name: cmplx-net-kp
-        vm_boot_timeout: 600
-        vm_delete_timeout: 120
-        ssh_connect_timeout: 120
-        ports:
-          - port:
-              name: site1-ovs-mgr-port
-              network_name: mgr-net
-          - port:
-              name: site1-ovs-site1-port
-              network_name: site1-net
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: site1-ovs-mgr-port
-              router_name: mgr-router
-    - instance:
-        name: site2-ovs
-        flavor: m1.small
-        imageName: Ubuntu-14.04
-        keypair_name: cmplx-net-kp
-        vm_boot_timeout: 600
-        vm_delete_timeout: 120
-        ssh_connect_timeout: 120
-        ports:
-          - port:
-              name: site2-ovs-mgr-port
-              network_name: mgr-net
-          - port:
-              name: site2-ovs-site2-port
-              network_name: site2-net
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: site2-ovs-mgr-port
-              subnet_name: mgr-subnet-2
-              router_name: mgr-router
-    - instance:
-        name: site2-host
-        flavor: m1.small
-        imageName: Ubuntu-14.04
-        keypair_name: cmplx-net-kp
-        vm_boot_timeout: 600
-        vm_delete_timeout: 120
-        ssh_connect_timeout: 120
-        ports:
-          - port:
-              name: site2-host-port
-              network_name: site2-net
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: site2-host-port
-              subnet_name: site2-subnet
-              router_name: site2-router
-# TODO - Add a playbook here...
-#ansible:
-#    - playbook_location: main.yml
-#      hosts:
-#        - mgr-app
-#        - site1-ovs
-#        - site2-ovs
-#        - site2-host
-#      variables:
-#        mac1:
-#          type: port
-#          vm_name: site1-ovs
-#          port_name: site1-ovs-site1-port
-#          port_value: mac_address
-#        ip1:
-#          type: port
-#          vm_name: site1-ovs
-#          port_name: site1-ovs-mgr-port
-#          port_value: ip_address
-#        mac2:
-#          type: port
-#          vm_name: site2-ovs
-#          port_name: site2-ovs-site2-port
-#          port_value: mac_address
-#        ip2:
-#          type: port
-#          vm_name: site2-ovs
-#          port_name: site2-ovs-mgr-port
-#          port_value: ip_address
-#    - playbook_location: ./main.yml
-#      hosts:
-#        - site1-ovs
-#        - site2-ovs
diff --git a/docs/examples/complex-network/main.yml b/docs/examples/complex-network/main.yml
deleted file mode 100644
index 7f213ea..0000000
--- a/docs/examples/complex-network/main.yml
+++ /dev/null
@@ -1,16 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-- include: playbooks/sample-playbook.yml
\ No newline at end of file
diff --git a/docs/examples/complex-network/playbooks/sample-playbook.yml b/docs/examples/complex-network/playbooks/sample-playbook.yml
deleted file mode 100644
index 726f213..0000000
--- a/docs/examples/complex-network/playbooks/sample-playbook.yml
+++ /dev/null
@@ -1,20 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-- hosts: all
-
-  tasks:
-   - name: Say hello
-     command: echo 'hello world' > ~/hello.out
diff --git a/docs/examples/external-network/deploy-ext-net.yaml b/docs/examples/external-network/deploy-ext-net.yaml
deleted file mode 100644
index 31c41ec..0000000
--- a/docs/examples/external-network/deploy-ext-net.yaml
+++ /dev/null
@@ -1,77 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-openstack:
-  connection:
-    # Note - when http_proxy is set, you must also configure ssh for proxy tunneling on your host.
-    username: admin
-    password: cable123
-    auth_url: http://10.197.103.50:5000/v2.0/
-    project_name: admin
-    http_proxy: localhost:3128
-  images:
-    - image:
-        name: Ubuntu
-        format: qcow2
-        image_user: ubuntu
-        download_url: http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img
-  networks:
-    - network:
-        name: ext-net
-        external: True
-        network_type: vlan
-        project_name: service
-        subnets:
-          - subnet:
-              name: ext-subnet
-              cidr: 10.197.101.0/24
-              gateway_ip: 10.197.101.1
-              start: 10.197.101.101
-              end: 10.197.101.200
-    - network:
-        name: internal-net
-        subnets:
-          - subnet:
-              name: internal-subnet
-              cidr: 10.0.1.0/24
-              dns_nameservers: [8.8.8.8]
-  routers:
-    - router:
-        name: ext-net-router
-        external_gateway: ext-net
-        internal_subnets:
-          - internal-subnet
-  keypairs:
-    - keypair:
-        name: ext-net-kp
-        public_filepath: /tmp/ext-net.pub
-        private_filepath: /tmp/ext-net
-  instances:
-    - instance:
-        name: ext-net-app
-        flavor: m1.small
-        imageName: Ubuntu
-        keypair_name: ext-net-kp
-        ports:
-          - port:
-              name: internal-net-port
-              network_name: internal-net
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: internal-net-port
-              router_name: ext-net-router
-              subnet_name: internal-subnet
-
diff --git a/docs/examples/simple/deploy-simple.yaml b/docs/examples/simple/deploy-simple.yaml
deleted file mode 100644
index ae946de..0000000
--- a/docs/examples/simple/deploy-simple.yaml
+++ /dev/null
@@ -1,101 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-openstack:
-  connection:
-    # Note - when http_proxy is set, you must also configure ssh for proxy tunneling on your host.
-    username: admin
-    password: cable123
-#    auth_url: http://10.197.103.50:5000/v2.0/
-    auth_url: http://192.168.67.10:5000/v2.0
-    project_name: admin
-    http_proxy: 10.197.123.27:3128
-    ssh_proxy_cmd: '/usr/local/bin/corkscrew 10.197.123.27 3128 %h %p'
-  images:
-    - image:
-        name: Ubuntu14
-        format: qcow2
-        image_user: ubuntu
-        download_url: http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img
-  networks:
-    - network:
-        name: simple-net
-        subnets:
-          - subnet:
-              name: simple-subnet
-              cidr: 10.0.1.0/24
-              dns_nameservers: [10.5.0.8, 8.8.8.8]
-  routers:
-    - router:
-        name: simple-router
-        external_gateway: external
-        internal_subnets:
-          - simple-subnet
-  keypairs:
-    - keypair:
-        name: simple
-        public_filepath: /tmp/simple.pub
-        private_filepath: /tmp/simple
-  instances:
-    - instance:
-        name: simple-1
-        flavor: m1.small
-        imageName: Ubuntu14
-        keypair_name: simple
-        userdata: "#cloud-config\npassword: cable123\nchpasswd: { expire: False }\nsshr_pwauth: True"
-        ports:
-          - port:
-              name: simple-net-port
-              network_name: simple-net
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: simple-net-port
-              router_name: simple-router
-              subnet_name: simple-subnet
-ansible:
-    - playbook_location: main.yml
-      hosts:
-        - simple-1
-      variables:
-        greeting_msg:
-          type: string
-          value: Greetings
-        os_user:
-          type: os_creds
-          value: username
-        os_pass:
-          type: os_creds
-          value: password
-        os_auth_url:
-          type: os_creds
-          value: auth_url
-        os_project:
-          type: os_creds
-          value: project_name
-        fip1:
-          type: vm-attr
-          vm_name: simple-1
-          value: floating_ip
-        mac1:
-          type: port
-          vm_name: simple-1
-          port_name: simple-net-port
-          port_value: mac_address
-        ip1:
-          type: port
-          vm_name: simple-1
-          port_name: simple-net-port
-          port_value: ip_address
\ No newline at end of file
diff --git a/docs/examples/simple/files/motd b/docs/examples/simple/files/motd
deleted file mode 100644
index cee5d06..0000000
--- a/docs/examples/simple/files/motd
+++ /dev/null
@@ -1,8 +0,0 @@
-{{ greeting_msg }}
-OS_USER - {{ os_user }}
-OS_PASSWORD - {{ os_pass }}
-AUTH_URL - {{ os_auth_url }}
-PROJECT_NAME - {{ os_project }}
-Floating IP - {{ fip1 }}
-Port MAC = {{ mac1 }}
-Port IP = {{ ip1 }}
diff --git a/docs/examples/simple/main.yml b/docs/examples/simple/main.yml
deleted file mode 100644
index 7f213ea..0000000
--- a/docs/examples/simple/main.yml
+++ /dev/null
@@ -1,16 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-- include: playbooks/sample-playbook.yml
\ No newline at end of file
diff --git a/docs/examples/simple/playbooks/sample-playbook.yml b/docs/examples/simple/playbooks/sample-playbook.yml
deleted file mode 100644
index 84c46e4..0000000
--- a/docs/examples/simple/playbooks/sample-playbook.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-- hosts: all
-  become: yes
-  become_method: sudo
-  become_user: root
-
-  tasks:
-   - name: Create MOTD
-     action: template owner=root group=root mode=666 src=../files/motd dest=/etc/motd
diff --git a/docs/examples/two-network/deploy-two-net-centos.yaml b/docs/examples/two-network/deploy-two-net-centos.yaml
deleted file mode 100644
index 4fae4aa..0000000
--- a/docs/examples/two-network/deploy-two-net-centos.yaml
+++ /dev/null
@@ -1,96 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-openstack:
-  connection:
-    # Note - when http_proxy is set, you must also configure ssh for proxy tunneling on your host.
-    username: admin
-    password: cable123
-    auth_url: http://10.197.103.50:5000/v2.0/
-    project_name: admin
-    http_proxy: localhost:3128
-  images:
-    - image:
-        name: centos
-        format: qcow2
-        image_user: centos
-        download_url: http://cloud.centos.org/centos/7/images/CentOS-7-x86_64-GenericCloud.qcow2
-        nic_config_pb_loc: provisioning/ansible/centos-network-setup/playbooks/configure_host.yml
-  networks:
-    - network:
-        name: net-1
-        subnets:
-          - subnet:
-              name: subnet-1
-              cidr: 10.0.1.0/24
-              dns_nameservers: [8.8.8.8]
-    - network:
-        name: net-2
-        subnets:
-          - subnet:
-              name: subnet-2
-              cidr: 10.0.2.0/24
-              dns_nameservers: [8.8.8.8]
-  routers:
-    - router:
-        name: router-1
-        external_gateway: external
-        internal_subnets:
-          - subnet-1
-  keypairs:
-    - keypair:
-        name: two-net
-        public_filepath: /tmp/two-net.pub
-        private_filepath: /tmp/two-net
-  instances:
-    - instance:
-        name: vm1
-        flavor: m1.small
-        imageName: centos
-        keypair_name: two-net
-        ports:
-          - port:
-              name: port-1-vm1
-              network_name: net-1
-          - port:
-              name: port-2-vm1
-              network_name: net-2
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: port-1-vm1
-              router_name: router-1
-              subnet_name: subnet-1
-    - instance:
-        name: vm2
-        flavor: m1.small
-        imageName: centos
-        keypair_name: two-net
-        ports:
-          - port:
-              name: port-1-vm2
-              network_name: net-1
-          - port:
-              name: port-2-vm2
-              network_name: net-2
-              ip_addrs:
-                - subnet_name: subnet-2
-                  ip: 10.0.2.101
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: port-1-vm2
-              router_name: router-1
-              subnet_name: subnet-1
\ No newline at end of file
diff --git a/docs/examples/two-network/deploy-two-net-ubuntu.yaml b/docs/examples/two-network/deploy-two-net-ubuntu.yaml
deleted file mode 100644
index ffcb05d..0000000
--- a/docs/examples/two-network/deploy-two-net-ubuntu.yaml
+++ /dev/null
@@ -1,96 +0,0 @@
-# Copyright (c) 2016 Cable Television Laboratories, Inc. ("CableLabs")
-#                    and others.  All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
----
-openstack:
-  connection:
-    # Note - when http_proxy is set, you must also configure ssh for proxy tunneling on your host.
-    username: admin
-    password: cable123
-    auth_url: http://10.197.103.50:5000/v2.0/
-    project_name: admin
-    http_proxy: localhost:3128
-  images:
-    - image:
-        name: Ubuntu
-        format: qcow2
-        image_user: ubuntu
-        download_url: http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img
-        nic_config_pb_loc: provisioning/ansible/ubuntu-network-setup/playbooks/configure_host.yml
-  networks:
-    - network:
-        name: net-1
-        subnets:
-          - subnet:
-              name: subnet-1
-              cidr: 10.0.1.0/24
-              dns_nameservers: [8.8.8.8]
-    - network:
-        name: net-2
-        subnets:
-          - subnet:
-              name: subnet-2
-              cidr: 10.0.2.0/24
-              dns_nameservers: [8.8.8.8]
-  routers:
-    - router:
-        name: router-1
-        external_gateway: external
-        internal_subnets:
-          - subnet-1
-  keypairs:
-    - keypair:
-        name: simple
-        public_filepath: /tmp/simple.pub
-        private_filepath: /tmp/simple
-  instances:
-    - instance:
-        name: vm1
-        flavor: m1.small
-        imageName: Ubuntu
-        keypair_name: simple
-        ports:
-          - port:
-              name: port-1-vm1
-              network_name: net-1
-          - port:
-              name: port-2-vm1
-              network_name: net-2
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: port-1-vm1
-              router_name: router-1
-              subnet_name: subnet-1
-    - instance:
-        name: vm2
-        flavor: m1.small
-        imageName: Ubuntu
-        keypair_name: simple
-        ports:
-          - port:
-              name: port-1-vm2
-              network_name: net-1
-          - port:
-              name: port-2-vm2
-              network_name: net-2
-              ip_addrs:
-                - subnet_name: subnet-2
-                  ip: 10.0.2.101
-        floating_ips:
-          - floating_ip:
-              name: fip1
-              port_name: port-1-vm2
-              router_name: router-1
-              subnet_name: subnet-1
\ No newline at end of file
diff --git a/docs/how-to-use/APITests.rst b/docs/how-to-use/APITests.rst
new file mode 100644
index 0000000..599325f
--- /dev/null
+++ b/docs/how-to-use/APITests.rst
@@ -0,0 +1,261 @@
+SNAPS OpenStack API Testing
+===========================
+
+Tests designated as component tests extend the snaps.openstack.tests.OSComponentTestCase class and must be exercised
+with OpenStack credentials for all as well as an external network for many. When leveraging the unit\_test\_suite.py
+application, the -e argument and -n arguments will suffice. When attempting to execute these tests within your IDE
+of choice (tested on IntelliJ), you will need to edit the [repo\_dir]/snaps/openstack/tests/conf/os\_env.yaml file as well
+as ensuring that your run configuration's working directory is set to [repo\_dir]/snaps.
+
+The Test Classes
+================
+
+glance_utils_tests.py - GlanceSmokeTests
+----------------------------------------
+
+Ensures that a Glance client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+keystone_utils_tests.py - KeystoneSmokeTests
+--------------------------------------------
+
+Ensures that a Keystone client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+neutron_utils_tests.py - NeutronSmokeTests
+------------------------------------------
+
+Ensures that a Neutron client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+nova_utils_tests.py - NovaSmokeTests
+------------------------------------
+
+Ensures that a Nova client can be obtained as well as the proper
+exceptions thrown with the wrong credentials.
+
+keystone_utils_tests.py - KeystoneUtilsTests
+--------------------------------------------
+
++----------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                        | Keystone API  | Description                                               |
++==================================+===============+===========================================================+
+| test_create_user_minimal         | 2 & 3         | Tests the creation of a user with minimal configuration   |
+|                                  |               | settings via the utility functions                        |
++----------------------------------+---------------+-----------------------------------------------------------+
+| test_create_project_minimal      | 2 & 3         | Tests the creation of a project with minimal configuration|
+|                                  |               | settings via the utility functions                        |
++----------------------------------+---------------+-----------------------------------------------------------+
+
+create_user_tests.py - CreateUserSuccessTests
+---------------------------------------------
++----------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                        | Keystone API  | Description                                               |
++==================================+===============+===========================================================+
+| test_create_user                 | 2 & 3         | Tests the creation of a user with minimal configuration   |
+|                                  |               | settings via the utility functions                        |
++----------------------------------+---------------+-----------------------------------------------------------+
+
+create_project_tests.py - CreateProjectSuccessTests
+---------------------------------------------------
+
++----------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                        | Keystone API  | Description                                               |
++==================================+===============+===========================================================+
+| test_create_user_minimal         | 2 & 3         | Tests the creation of a user via the OpenStackUser class  |
++----------------------------------+---------------+-----------------------------------------------------------+
+| test_create_user_2x              | 2 & 3         | Tests the creation of a user a second time via the        |
+|                                  |               | OpenStackUser class to ensure it is only created once     |
++----------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_user          | 2 & 3         | Tests the creation and deletion of a user via the         |
+|                                  |               | OpenStackUser class to ensure that clean will not raise   |
+|                                  |               | an exception                                              |
++----------------------------------+---------------+-----------------------------------------------------------+
+
+create_project_tests.py - CreateProjectUserTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Keystone API  | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_project_sec_grp_one_user  | 2 & 3         | Tests the creation of an OpenStack object to a project    |
+|                                       |               | with a new users and to create a security group           |
+|                                       |               |                                                           |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_project_sec_grp_two_users | 2 & 3         | Tests the creation of an OpenStack object to a project    |
+|                                       |               | with two new users and to create a security group under   |
+|                                       |               | each                                                      |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+glance_utils_tests.py - GlanceUtilsTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Glance API    | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_image_minimal_url         | 1             | Tests the glance_utils.create_image() function with a URL |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_image_minimal_file        | 1             | Tests the glance_utils.create_image() function with a file|
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsNetworkTests
+-------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Neutron API   | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_network                   | 2             | Ensures neutron_utils.create_network() properly creates a |
+|                                       |               | network                                                   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_network_empty_name        | 2             | Ensures neutron_utils.create_network() raises an exception|
+|                                       |               | when the network name is an empty string                  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_network_null_name         | 2             | Ensures neutron_utils.create_network() raises an exception|
+|                                       |               | when the network name is None                             |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsSubnetTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Neutron API   | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_subnet                    | 2             | Ensures neutron_utils.create_subnet() can properly create |
+|                                       |               | an OpenStack subnet object                                |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_null_name          | 2             | Ensures neutron_utils.create_subnet() raises an exception |
+|                                       |               | when the subnet name is None                              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_empty_name         | 2             | Ensures neutron_utils.create_subnet() raises an exception |
+|                                       |               | when the subnet name is an empty string                   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_null_cidr          | 2             | Ensures neutron_utils.create_subnet() raises an exception |
+|                                       |               | when the subnet CIDR is None                              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_subnet_empty_cidr         | 2             | Ensures neutron_utils.create_subnet() raises an exception |
+|                                       |               | when the subnet CIDR is an empty string                   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsRouterTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Neutron API   | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_router_simple             | 2             | Ensures neutron_utils.create_router() can properly create |
+|                                       |               | a simple OpenStack router object                          |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_with_public_inter  | 2             | Ensures neutron_utils.create_router() can properly create |
+| face                                  |               | an OpenStack router object with an interface to the       |
+|                                       |               | external network                                          |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_empty_name         | 2             | Ensures neutron_utils.create_router() raises an exception |
+|                                       |               | when the name is an empty string                          |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_null_name          | 2             | Ensures neutron_utils.create_router() raises an exception |
+|                                       |               | when the name is None                                     |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_interface_router             | 2             | Ensures neutron_utils.add_interface_router() properly adds|
+|                                       |               | an interface to another subnet                            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_interface_router_null_router | 2             | Ensures neutron_utils.add_interface_router() raises an    |
+|                                       |               | exception when the router object is None                  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_interface_router_null_subnet | 2             | Ensures neutron_utils.add_interface_router() raises an    |
+|                                       |               | exception when the subnet object is None                  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port                      | 2             | Ensures neutron_utils.create_port() can properly create an|
+|                                       |               | OpenStack port object                                     |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_empty_name           | 2             | Ensures neutron_utils.create_port() raises an exception   |
+|                                       |               | when the port name is an empty string                     |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_null_name            | 2             | Ensures neutron_utils.create_port() raises an exception   |
+|                                       |               | when the port name is None                                |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_null_network_object  | 2             | Ensures neutron_utils.create_port() raises an exception   |
+|                                       |               | when the network object is None                           |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_null_ip              | 2             | Ensures neutron_utils.create_port() raises an exception   |
+|                                       |               | when the assigned IP value is None                        |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_invalid_ip           | 2             | Ensures neutron_utils.create_port() raises an exception   |
+|                                       |               | when the assigned IP value is invalid                     |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_port_invalid_ip_to_subnet | 2             | Ensures neutron_utils.create_port() raises an exception   |
+|                                       |               | when the assigned IP value is not part of CIDR            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+neutron_utils_tests.py - NeutronUtilsSecurityGroupTests
+-------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Neutron API   | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_delete_simple_sec_grp     | 2             | Ensures that a security group can be created              |
+|                                       |               | (neutron_utils.create_security_group() and deleted via    |
+|                                       |               | neutron_utils.delete_security_group()                     |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_sec_grp_no_name           | 2             | Ensures that neutron_utils.create_security_group() raises |
+|                                       |               | an exception when attempting to create a security group   |
+|                                       |               | without a name                                            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_sec_grp_no_rules          | 2             | Ensures that neutron_utils.create_security_group() can    |
+|                                       |               | create a security group without any rules                 |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_sec_grp_one_rule          | 2             | Ensures that neutron_utils.create_security_group_rule()   |
+|                                       |               | can add a rule to a security group                        |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+nova_utils_tests.py - NovaUtilsKeypairTests
+-------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Nova API      | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_keypair                   | 2             | Ensures that a keypair can be properly created via        |
+|                                       |               | nova_utils.upload_keypair() with a public_key object      |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_keypair            | 2             | Ensures that a keypair can be properly deleted via        |
+|                                       |               | nova_utils.delete_keypair()                               |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_key_from_file             | 2             | Ensures that a keypair can be properly created via        |
+|                                       |               | nova_utils.upload_keypair_file()                          |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_floating_ips                     | 2             | Ensures that a floating IP can be properly created via    |
+|                                       |               | nova_utils.create_floating_ip() [note: this test should   |
+|                                       |               | be moved to a new class]                                  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+nova_utils_tests.py - NovaUtilsFlavorTests
+------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Nova API      | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_flavor                    | 2             | Ensures that a flavor can be properly created via         |
+|                                       |               | nova_utils.create_flavor()                                |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_flavor             | 2             | Ensures that a flavor can be properly deleted via         |
+|                                       |               | nova_utils.delete_flavor()                                |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_flavor_tests.py - CreateFlavorTests
+------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Nova API      | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_flavor                    | 2             | Ensures that the OpenStackFlavor class's create() method  |
+|                                       |               | creates an OpenStack flavor object                        |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_flavor_existing           | 2             | Ensures that the OpenStackFlavor class's create() will not|
+|                                       |               | create a flavor with the same name more than once         |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_clean_flavor              | 2             | Ensures that the OpenStackFlavor class's clean() method   |
+|                                       |               | will delete the flavor object                             |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_flavor             | 2             | Ensures that the OpenStackFlavor class's clean() method   |
+|                                       |               | will not raise an exception when called and the object no |
+|                                       |               | longer exists                                             |
++---------------------------------------+---------------+-----------------------------------------------------------+
diff --git a/docs/how-to-use/IntegrationTests.rst b/docs/how-to-use/IntegrationTests.rst
new file mode 100644
index 0000000..983c165
--- /dev/null
+++ b/docs/how-to-use/IntegrationTests.rst
@@ -0,0 +1,290 @@
+SNAPS OpenStack Integration Testing
+===================================
+
+These tests are ones designed to be run within their own dynamically created project along with a newly generated user
+account and generally require other OpenStack object creators.
+
+The Test Classes
+================
+
+create_security_group_tests.py - CreateSecurityGroupTests
+---------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_group_without_rules       | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class can create a     |
+|                                       | Neutron 2     | security group without any rules                          |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_group              | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class clean() method   |
+|                                       | Neutron 2     | will not raise an exception should the group be deleted by|
+|                                       |               | some other process                                        |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_group_with_one_simple_rule| Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class can create a     |
+|                                       | Neutron 2     | security group with a single rule                         |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_group_with_several_rules  | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup class can create a     |
+|                                       | Neutron 2     | security group with several rules                         |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_rule                         | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup#add_rule() method      |
+|                                       | Neutron 2     | properly creates and associates the new rule              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_rule_by_id                | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup#remove_rule() method   |
+|                                       | Neutron 2     | properly deletes and disassociates the old rule via its ID|
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_rule_by_setting           | Keysone 2 & 3 | Ensures the OpenStackSecurityGroup#remove_rule() method   |
+|                                       | Neutron 2     | properly deletes and disassociates the old rule via its   |
+|                                       |               | setting object                                            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_image_tests.py - CreateImageSuccessTests
+-----------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Glance API    | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_image_clean_url           | 1             | Ensures the OpenStackImage class can create an image from |
+|                                       |               | a download URL location                                   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_image_clean_file          | 1             | Ensures the OpenStackImage class can create an image from |
+|                                       |               | a locally sourced image file                              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_image              | 1             | Ensures the OpenStackImage.clean() method deletes an image|
+|                                       |               | and does not raise an exception on subsequent calls to the|
+|                                       |               | clean() method                                            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_same_image                | 1             | Ensures the OpenStackImage.create() method does not create|
+|                                       |               | another image when one already exists with the same name  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_image_tests.py - CreateImageNegativeTests
+------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Glance API    | Description                                               |
++=======================================+===============+===========================================================+
+| test_none_image_name                  | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the ImageSettings.name attribute has    |
+|                                       |               | not been set                                              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_bad_image_url                    | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the download URL is invalid             |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_bad_image_file                   | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the image file does not exist           |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_proj_name                   | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the credentials project name is None    |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_auth_url                    | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the credentials URL is None             |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_password                    | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the credentials password is None        |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_none_user                        | 1             | Ensures OpenStackImage.create() results in an Exception   |
+|                                       |               | being raised when the credentials user is None            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_keypairs_tests.py - CreateKeypairsTests
+----------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Nova API      | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_keypair_only              | 2             | Ensures that a keypair object can be created simply by    |
+|                                       |               | only configuring a name                                   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_keypair            | 2             | Ensures that a keypair object is deleted via              |
+|                                       |               | OpenStackKeypair.clean() and subsequent calls do not      |
+|                                       |               | result in exceptions                                      |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_keypair_save_pub_only     | 2             | Ensures that a keypair object can be created when the only|
+|                                       |               | the public key is cached to disk                          |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_keypair_save_both         | 2             | Ensures that a keypair object can be created when both the|
+|                                       |               | public and private keys are cached to disk                |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_keypair_from_file         | 2             | Ensures that a keypair object can be created with an      |
+|                                       |               | existing public key file                                  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_network_tests.py - CreateNetworkSuccessTests
+---------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Neutron API   | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_network_without_router    | 2             | Ensures that a network can be created via the             |
+|                                       |               | OpenStackNetwork class without any routers                |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_network            | 2             | Ensures that a router can be deleted via the              |
+|                                       |               | OpenStackNetwork.clean() method                           |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_network_with_router       | 2             | Ensures that a network can be created via the             |
+|                                       |               | OpenStackNetwork class with a router                      |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_networks_same_name        | 2             | Ensures that the OpenStackNetwork.create() method will not|
+|                                       |               | create a network with the same name                       |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_router_tests.py - CreateRouterSuccessTests
+-------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | Neutron API   | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_router_vanilla            | 2             | Ensures that a router can be created via the              |
+|                                       |               | OpenStackRouter class with minimal settings               |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_delete_router             | 2             | Ensures that a router can be deleted via the              |
+|                                       |               | OpenStackRouter.clean() method                            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_admin_state_false  | 2             | Ensures that a router can created with                    |
+|                                       |               | admin_state_up = False                                    |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_admin_state_True   | 2             | Ensures that a router can created with                    |
+|                                       |               | admin_state_up = True                                     |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_private_network    | 2             | Ensures that a router port can be created against a       |
+|                                       |               | private network                                           |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_external_network   | 2             | Ensures that a router can be created that is connected to |
+|                                       |               | both external and private internal networks               |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_router_tests.py - CreateRouterNegativeTests
+--------------------------------------------------
+
++----------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                              | Neutron API   | Description                                               |
++========================================+===============+===========================================================+
+| test_create_router_noname              | 2             | Ensures that an exception is raised when attempting to    |
+|                                        |               | create a router without a name                            |
++----------------------------------------+---------------+-----------------------------------------------------------+
+| test_create_router_invalid_gateway_name| 2             | Ensures that an exception is raised when attempting to    |
+|                                        |               | create a router to an external network that does not exist|
++----------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstanceSimpleTests
+----------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_create_delete_instance           | Nova 2        | Ensures that the OpenStackVmInstance.clean() method       |
+|                                       | Neutron 2     | deletes the instance                                      |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - SimpleHealthCheck
+--------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_check_vm_ip_dhcp                 | Nova 2        | Tests the creation of an OpenStack instance with a single |
+|                                       | Neutron 2     | port and it's assigned IP address                         |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstanceSingleNetworkTests
+-----------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_single_port_static               | Nova 2        | Ensures that an instance with a single port/NIC with a    |
+|                                       | Neutron 2     | static IP can be created                                  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_ssh_client_fip_before_active     | Nova 2        | Ensures that an instance can be reached over SSH when the |
+|                                       | Neutron 2     | floating IP is assigned prior to the VM becoming ACTIVE   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_ssh_client_fip_after_active      | Nova 2        | Ensures that an instance can be reached over SSH when the |
+|                                       | Neutron 2     | floating IP is assigned after to the VM becoming ACTIVE   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstancePortManipulationTests
+--------------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_set_custom_valid_ip_one_subnet   | Nova 2        | Ensures that an instance's can have a valid static IP is  |
+|                                       | Neutron 2     | properly assigned                                         |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_invalid_ip_one_subnet | Nova 2        | Ensures that an instance's port with an invalid static IP |
+|                                       | Neutron 2     | raises an exception                                       |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_valid_mac             | Nova 2        | Ensures that an instance's port can have a valid MAC      |
+|                                       | Neutron 2     | address properly assigned                                 |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_invalid_mac           | Nova 2        | Ensures that an instance's port with an invalid MAC       |
+|                                       | Neutron 2     | address raises and exception                              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_custom_mac_and_ip            | Nova 2        | Ensures that an instance's port with a valid static IP and|
+|                                       | Neutron 2     | MAC are properly assigned                                 |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_allowed_address_pairs        | Nova 2        | Ensures the configured allowed_address_pairs is properly  |
+|                                       | Neutron 2     | set on a VMs port                                         |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_allowed_address_pairs_bad_mac| Nova 2        | Ensures the port cannot be created when a bad MAC address |
+|                                       | Neutron 2     | format is used in the allowed_address_pairs port attribute|
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_set_allowed_address_pairs_bad_ip | Nova 2        | Ensures the port cannot be created when a bad IP address  |
+|                                       | Neutron 2     | format is used in the allowed_address_pairs port attribute|
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstanceOnComputeHost
+------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_deploy_vm_to_each_compute_node   | Nova 2        | Tests to ensure that one can fire up an instance on each  |
+|                                       | Neutron 2     | active compute node                                       |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - CreateInstancePubPrivNetTests
+--------------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_dual_ports_dhcp                  | Nova 2        | Ensures that a VM with two ports/NICs can have its second |
+|                                       | Neutron 2     | NIC configured via SSH/Ansible after startup              |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+create_instance_tests.py - InstanceSecurityGroupTests
+-----------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_add_security_group               | Nova 2        | Ensures that a VM instance can have security group added  |
+|                                       | Neutron 2     | to it while its running                                   |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_invalid_security_group       | Nova 2        | Ensures that a VM instance does not accept the addition of|
+|                                       | Neutron 2     | a security group that no longer exists                    |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_security_group            | Nova 2        | Ensures that a VM instance accepts the removal of a       |
+|                                       | Neutron 2     | security group                                            |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_remove_security_group_never_added| Nova 2        | Ensures that a VM instance does not accept the removal of |
+|                                       | Neutron 2     | a security group that was never added in the first place  |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_add_same_security_group          | Nova 2        | Ensures that a VM instance does not add a security group  |
+|                                       | Neutron 2     | that has already been added to the instance               |
++---------------------------------------+---------------+-----------------------------------------------------------+
+
+ansible_utils_tests.py - AnsibleProvisioningTests
+-------------------------------------------------
+
++---------------------------------------+---------------+-----------------------------------------------------------+
+| Test Name                             | API Versions  | Description                                               |
++=======================================+===============+===========================================================+
+| test_apply_simple_playbook            | Nova 2        | Ensures that an instance assigned with a floating IP will |
+|                                       | Neutron 2     | apply a simple Ansible playbook                           |
++---------------------------------------+---------------+-----------------------------------------------------------+
+| test_apply_template_playbook          | Nova 2        | Ensures that an instance assigned with a floating IP will |
+|                                       | Neutron 2     | apply a Ansible playbook containing Jinga2 substitution   |
+|                                       |               | values                                                    |
++---------------------------------------+---------------+-----------------------------------------------------------+
diff --git a/docs/how-to-use/Testing.rst b/docs/how-to-use/Testing.rst
new file mode 100644
index 0000000..586974a
--- /dev/null
+++ b/docs/how-to-use/Testing.rst
@@ -0,0 +1,44 @@
+Running Unit Test Suite
+=======================
+
+These tests are written in Python and require an that it is setup before running the tests.
+See `install directions <index.md>`__ for Python installation instructions.
+
+Start by cloning the snaps-provisioning repository
+--------------------------------------------------
+
+``git clone https://gerrit.cablelabs.com/snaps-provisioning``
+
+Install Library
+---------------
+
+``pip install -e <path to repo>/``
+
+Execute the tests
+-----------------
+
+| ``cd <path to repo>   python snaps/unit_test_suite.py -e [path to RC file] -n [external network name]``
+| \* All Supported Arguments
+| \* -e [required - The path to the OpenStack RC file]
+| \* -n [required - The name of the external network to use for routers
+  and floating IPs]
+| \* -p [optional - the proxy settings if required. Format :
+| \* -s [optional - the proxy command used for SSH connections]
+| \* -l [(default INFO) The log level]
+| \* -k [optional - When set, tests project and user creation. Use only
+  if host running tests has access to the cloud's admin network]
+| \* -f [optional - When set, will not execute tests requiring Floating
+  IPS]
+| \* -u [optional - When set, the unit tests will be executed]
+
+Test descriptions
+=================
+
+`Unit Testing <UnitTests.rst>`__ - Tests that do not require a connection to OpenStack
+--------------------------------------------------------------------------------------
+
+`OpenStack API Tests <APITests.rst>`__ - Tests many individual OpenStack API calls
+----------------------------------------------------------------------------------
+
+`Integration Tests <IntegrationTests.rst>`__ - Tests OpenStack object creation in a context. These tests will be run within a custom project as a specific user.
+----------------------------------------------------------------------------------------------------------------------------------------------------------------
diff --git a/docs/how-to-use/UnitTests.rst b/docs/how-to-use/UnitTests.rst
new file mode 100644
index 0000000..efd6426
--- /dev/null
+++ b/docs/how-to-use/UnitTests.rst
@@ -0,0 +1,91 @@
+SNAPS Unit Testing
+==================
+
+| Tests designated as Unit tests extend the unittest.TestCase class and
+  can be exercised without any external resources
+| other than the filesystem. Most of these tests simply ensure that the
+  configuration settings classes check their
+| constructor arguments properly.
+
+The Test Classes
+================
+
+FileUtilsTests
+--------------
+
+-  testFileIsDirectory - ensures that the expected path is a directory
+-  testFileNotExist - ensures that a file that does not exist returns
+   False
+-  testFileExists - ensures that a file that does exist returns True
+-  testDownloadBadUrl - ensures that an Exception is thrown when
+   attempting to download a file with a bad URL
+-  testCirrosImageDownload - ensures that the Cirros image can be
+   downloaded
+-  testReadOSEnvFile - ensures that an OpenStack RC file can be properly
+   parsed
+
+SecurityGroupRuleSettingsUnitTests
+----------------------------------
+
+Ensures that all required members are included when constructing a
+SecurityGroupRuleSettings object
+
+SecurityGroupSettingsUnitTests
+------------------------------
+
+Ensures that all required members are included when constructing a
+SecuirtyGroupSettings object
+
+ImageSettingsUnitTests
+----------------------
+
+Ensures that all required members are included when constructing a
+ImageSettings object
+
+KeypairSettingsUnitTests
+------------------------
+
+Ensures that all required members are included when constructing a
+KeypairSettings object
+
+UserSettingsUnitTests
+---------------------
+
+Ensures that all required members are included when constructing a
+UserSettings object
+
+ProjectSettingsUnitTests
+------------------------
+
+Ensures that all required members are included when constructing a
+ProjectSettings object
+
+NetworkSettingsUnitTests
+------------------------
+
+Ensures that all required members are included when constructing a
+NetworkSettings object
+
+SubnetSettingsUnitTests
+-----------------------
+
+Ensures that all required members are included when constructing a
+SubnetSettings object
+
+PortSettingsUnitTests
+---------------------
+
+Ensures that all required members are included when constructing a
+PortSettings object
+
+FloatingIpSettingsUnitTests
+---------------------------
+
+Ensures that all required members are included when constructing a
+FloatingIpSettings object
+
+VmInstanceSettingsUnitTests
+---------------------------
+
+Ensures that all required members are included when constructing a
+VmInstanceSettings object
diff --git a/docs/how-to-use/VirtEnvDeploy.rst b/docs/how-to-use/VirtEnvDeploy.rst
new file mode 100644
index 0000000..7f55f0c
--- /dev/null
+++ b/docs/how-to-use/VirtEnvDeploy.rst
@@ -0,0 +1,275 @@
+Overview
+========
+
+The main purpose of this project is to enable one to describe a virtual environment in a YAML file and enable the
+user to deploy it to an OpenStack cloud in a repeatable manner. There are also options to un-deploy that same
+environment by leveraging the original YAML file.
+
+To deploy/clean virtual environments
+====================================
+
+-  Clone Repository
+
+   -  git clone https://gerrit.cablelabs.com/snaps-provisioning
+
+-  Install Library
+
+   -  pip install -e /
+
+-  Deploy
+
+   -  cd
+   -  python snaps/deploy\_venv.py -e -d
+   -  Working example:
+
+::
+
+    python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -d
+
+-  Clean
+
+   -  python deploy\_venv.py -e -c
+   -  Working example (cleanup of a previously deployed virtual
+      environment where the VM has Yardstick installed):
+
+::
+
+    python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -c
+
+Environment Configuration YAML File
+===================================
+
+The configuration file used to deploy and provision a virtual environment has been designed to describe the required
+images, networks, SSH public and private keys, associated VMs, as well as any required post deployment provisioning
+tasks.
+
+\*\*\* Please note that many of the more esoteric optional supported
+attributes still have not been fully tested. ***
+*** Some of the nested bullets are being hidden by GitLabs, please see
+doc/VirtEnvDeploy.md.\*\*\*
+
+-  openstack: the top level tag that denotes configuration for the
+   OpenStack components
+
+   -  connection: - contains the credentials and endpoints required to
+      connect with OpenStack
+   -  username: - the project's user (required)
+   -  password: - the tentant's user password (required)
+   -  auth\_url: - the URL to the OpenStack APIs (required)
+   -  project\_name: - the name of the OpenStack project for the user
+      (required)
+   -  http\_proxy: - the {{ host }}:{{ port }} of the proxy server the
+      HTTPPhotoman01(optional)
+   -  images: - describes each image
+   -  image:
+
+      -  name: The unique image name. If the name already exists for
+         your project, a new one will not be created (required)
+      -  format: The format type of the image i.e. qcow2 (required)
+      -  download\_url: The HTTP download location of the image file
+         (required)
+      -  nic\_config\_pb\_loc: The file location relative to the CWD
+         (python directory) to the Ansible Playbook used to configure
+         VMs with more than one port. VMs get their first NIC configured
+         for free while subsequent ones are not. This value/script will
+         only be leveraged when necessary. Centos has been supported
+         with
+         "provisioning/ansible/centos-network-setup/configure\_host.yml".
+
+   -  networks:
+   -  network:
+
+      -  name: The name of the network to be created. If one already
+         exists, a new one will not be created (required)
+      -  admin\_state\_up: T\|F (default True)
+      -  shared: (optional)
+      -  project\_name: Name of the project who owns the network. Note:
+         only administrative users can specify projects other than their
+         own (optional)
+      -  external: T\|F whether or not network is external (default
+         False)
+      -  network\_type: The type of network to create. (optional)
+      -  subnets:
+      -  subnet:
+
+         -  name: The name of the network to be created. If one already
+            exists, a new one will not be created. Note: although
+            OpenStack allows for multiple subnets to be applied to any
+            given network, we have not included support as our current
+            use cases does not utilize this functionality (required)
+         -  cidr: The subnet mask value (required)
+         -  dns\_nameservers: A list of IP values used for DNS
+            resolution (default: 8.8.8.8)
+         -  ip\_version: 4\|6 (default: 4)
+         -  project\_name: Name of the project who owns the network.
+            Note: only administrative users can specify projects other
+            than their own (optional)
+         -  start: The start address for allocation\_pools (optional)
+         -  end: The ending address for allocation\_pools (optional)
+         -  gateway\_ip: The IP address to the gateway (optional)
+         -  enable\_dhcp: T\|F (optional)
+         -  dns\_nameservers: List of DNS server IPs
+         -  host\_routes: A list of host route dictionaries (optional)
+            i.e.:
+            ``yaml    "host_routes":[    {    "destination":"0.0.0.0/0",    "nexthop":"123.456.78.9"    },    {    "destination":"192.168.0.0/24",    "nexthop":"192.168.0.1"    }    ]``
+         -  destination: The destination for a static route (optional)
+         -  nexthop: The next hop for the destination (optional)
+         -  ipv6\_ra\_mode: Valid values: "dhcpv6-stateful",
+            "dhcpv6-stateless", and "slaac" (optional)
+         -  ipv6\_address\_mode: Valid values: "dhcpv6-stateful",
+            "dhcpv6-stateless", and "slaac" (optional)
+
+   -  routers:
+
+      -  router:
+      -  name: The name of the router to be created. If one already
+         exists, a new one will not be created (required)
+      -  project\_name: Name of the project who owns the network. Note:
+         only administrative users can specify projects other than their
+         own (optional)
+      -  internal\_subnets: A list of subnet names on which the router
+         will be placed (optional)
+      -  external\_gateway: A dictionary containing the external gateway
+         parameters: "network\_id", "enable\_snat",
+         "external\_fixed\_ips" (optional)
+      -  interfaces: A list of port interfaces to create to other
+         subnets (optional)
+
+         -  port (Leverages the same class/structure as port objects on
+            VM instances. See port definition below for a
+            full accounting of the port attributes. The ones listed
+            below are generally used for routers)
+
+            -  name: The name given to the new port (must be unique for
+               project) (required)
+            -  network\_name: The name of the new port's network
+               (required)
+            -  ip\_addrs: A list of k/v pairs (optional)
+            -  subnet\_name: the name of a subnet that is on the port's
+               network
+            -  ip: An IP address of the associated subnet to assign to
+               the new port (optional but generally required for router
+               interfaces)
+
+   -  keypairs:
+
+      -  keypair:
+      -  name: The name of the keypair to be created. If one already
+         exists, a new one will not be created but simply loaded from
+         its configured file location (required)
+      -  public\_filepath: The path to where the generated public key
+         will be stored if it does not exist (optional but really
+         required for provisioning purposes)
+      -  private\_filepath: The path to where the generated private key
+         will be stored if it does not exist (optional but really
+         required for provisioning purposes)
+
+   -  instances:
+
+      -  instance:
+      -  name: The unique instance name for project. (required)
+      -  flavor: Must be one of the preconfigured flavors (required)
+      -  imageName: The name of the image to be used for deployment
+         (required)
+      -  keypair\_name: The name of the keypair to attach to instance
+         (optional but required for NIC configuration and Ansible
+         provisioning)
+      -  sudo\_user: The name of a sudo\_user that is attached to the
+         keypair (optional but required for NIC configuration and
+         Ansible provisioning)
+      -  vm\_boot\_timeout: The number of seconds to block waiting for
+         an instance to deploy and boot (default 900)
+      -  vm\_delete\_timeout: The number of seconds to block waiting for
+         an instance to be deleted (default 300)
+      -  ssh\_connect\_timeout: The number of seconds to block waiting
+         for an instance to achieve an SSH connection (default 120)
+      -  ports: A list of port configurations (should contain at least
+         one)
+      -  port: Denotes the configuration of a NIC
+
+         -  name: The unique port name for project (required)
+         -  network\_name: The name of the network to which the port is
+            attached (required)
+         -  ip\_addrs: Static IP addresses to be added to the port by
+            subnet (optional)
+         -  subnet\_name: The name of the subnet
+         -  ip: The assigned IP address (when null, OpenStack will
+            assign an IP to the port)
+         -  admin\_state\_up: T\|F (default True)
+         -  project\_name: The name of the project who owns the network.
+            Only administrative users can specify a the project ID other
+            than their own (optional)
+         -  mac\_address: The desired MAC for the port (optional)
+         -  fixed\_ips: A dictionary that allows one to specify only a
+            subnet ID, OpenStack Networking allocates an available IP
+            from that subnet to the port. If you specify both a subnet
+            ID and an IP address, OpenStack Networking tries to allocate
+            the specified address to the port. (optional)
+         -  seurity\_groups: A list of security group IDs (optional)
+         -  allowed\_address\_pairs: A dictionary containing a set of
+            zero or more allowed address pairs. An address pair contains
+            an IP address and MAC address. (optional)
+         -  opt\_value: The extra DHCP option value (optional)
+         -  opt\_name: The extra DHCP option name (optional)
+         -  device\_owner: The ID of the entity that uses this port. For
+            example, a DHCP agent (optional)
+         -  device\_id: The ID of the device that uses this port. For
+            example, a virtual server (optional)
+
+   -  floating\_ips: list of floating\_ip configurations (optional)
+
+      -  floating\_ip:
+      -  name: Must be unique for VM instance (required)
+      -  port\_name: The name of the port requiring access to the
+         external network (required)
+      -  subnet\_name: The name of the subnet contains the IP address on
+         the port on which to create the floating IP (optional)
+      -  router\_name: The name of the router connected to an external
+         network used to attach the floating IP (required)
+      -  provisioning: (True\|False) Denotes whether or not this IP can
+         be used for Ansible provisioning (default True)
+
+-  ansible: Each set of attributes below are contained in a list
+
+   -  playbook\_location: Full path or relative to the directory in
+      which the deployment file resides (required)
+   -  hosts: A list of hosts to which the playbook will be executed
+      (required)
+   -  variables: Should your Ansible scripts require any substitution
+      values to be applied with Jinga2templates, the values defined here
+      will be used to for substitution
+   -  tag name = substitution variable names. For instance, for any file
+      being pushed to the host being provisioned containing a value such
+      as {{ foo }}, you must specify a tag name of "foo"
+
+      -  vm\_name:
+      -  type: string\|port\|os\_creds\|vm-attr (note: will need to make
+         changes to deploy\_venv.py#\_\_get\_variable\_value() for
+         additional support)
+      -  when type == string, an tag name "value" must exist and its
+         value will be used for template substituion
+      -  when type == port, custom code has been written to extract
+         certain assigned values to the port:
+
+         -  vm\_name: must correspond to a VM's name as configured in
+            this file
+         -  port\_name: The name of the port from which to extract the
+            substitution values (required)
+         -  port\_value: The port value. Currently only supporting
+            "mac\_address" and "ip\_address" (only the first)
+
+      -  when type == os\_creds, custom code has been written to extract
+         the file's connection values:
+
+         -  username: connection's user
+         -  password: connection's password
+         -  auth\_url: connection's URL
+         -  project\_name: connection's project
+
+      -  when type == vm-attr, custom code has been written to extract
+         the following attributes from the vm:
+
+         -  vm\_name: must correspond to a VM's name as configured in
+            this file
+         -  value -> floating\_ip: is currently the only vm-attr
+            supported
diff --git a/docs/how-to-use/index.rst b/docs/how-to-use/index.rst
new file mode 100644
index 0000000..58b67a3
--- /dev/null
+++ b/docs/how-to-use/index.rst
@@ -0,0 +1,26 @@
+*************************
+Runtime Environment Setup
+*************************
+
+-  Python 2.7 (recommend leveraging a Virtual Python runtime, e.g.
+   `Virtualenv <https://virtualenv.pypa.io>`__, in your development
+   environment)
+-  Development packages for python and openssl. On CentOS/RHEL:
+
+   # yum install python-devel openssl-devel
+
+On Ubuntu:
+
+::
+
+      # apt-get install python2.7-dev libssl-dev
+
+-  Install SNAPS Library
+
+   -  pip install -e <path to repo>/snaps/
+
+`Testing <Testing.rst>`__
+-------------------------
+
+`Virtual Environment Deployment <VirtEnvDeploy.rst>`__
+------------------------------------------------------
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index 536bc15..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Python scripts for creating virtual environments on OpenStack with Ansible playbooks for provisioning.
-
-## Runtime Environment Setup
-  * Python 2.7 (recommend leveraging a Virtual Python runtime, e.g. [Virtualenv](https://virtualenv.pypa.io), in your development environment)
-  * Development packages for python and openssl. On CentOS/RHEL:
-
-      \# yum install python-devel openssl-devel
-
-  On Ubuntu:
-
-      \# apt-get install python2.7-dev libssl-dev
-  * Install SNAPS Library
-    * pip install -e &lt;path to repo>/snaps/
-
-## [Testing](Testing.md)
-## [Virtual Environment Deployment](VirtEnvDeploy.md)
-
-Also see the [CableLabs project wiki page](https://community.cablelabs.com/wiki/display/SNAPS/OpenStack+Instantiation%2C+Provisioning%2C+and+Testing)
-for more information on these scripts.