[DOCS] Cleanup the role docs for consistency and clarity

Utilizing RST includes to reduce duplication of documentation
effort. All contents of the Ansible defaults/main.yml are
now included in the documentation directly.

Change-Id: Ic3432433435a849913f243ea37302a484787256e

README.rst

@@ -1,15 +1,46 @@
-OpenStack cinder
-################
-:tags: openstack, cinder, cloud, ansible
-:category: \*nix
+OpenStack-Ansible Cinder
+########################
 
-Role for deployment, setup and installation of cinder.
+This Ansible role installs and configures OpenStack Cinder.
 
-This role will install the following:
+The following Cinder services are managed by the role:
     * cinder-api
     * cinder-volume
     * cinder-scheduler
 
+By default, Cinder API v1 and v2 are both enabled.
+
+Support for various Cinder backends is supported by the role. See role
+internals for further details.
+
+Support for volume backups to Swift or Ceph is support by the role. See role
+internals for further details.
+
+Default Variables
+=================
+
+.. literalinclude:: ../../defaults/main.yml
+   :language: yaml
+   :start-after: under the License.
+
+
+Required Variables
+==================
+
+This list is not exhaustive at present. See role internals for further
+details.
+
+.. code-block:: yaml
+
+      # Comma separated list of Glance API servers
+      cinder_glance_api_servers: "http://glance_server:9292"
+
+      # Hostname or IP address of the Galera database
+      cinder_galera_address: "1.2.3.4"
+
+Example Playbook
+================
+
 .. code-block:: yaml
 
     - name: Installation and setup of cinder
@@ -18,4 +49,5 @@ This role will install the following:
       roles:
         - { role: "os_cinder", tags: [ "os-cinder" ] }
       vars:
+        cinder_glance_api_servers: "http://glance_server:9292"
         cinder_galera_address: "{{ internal_lb_vip_address }}"

defaults/main.yml

@@ -13,9 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Defines that the role will be deployed on a host machine
-is_metal: true
-
 ## APT Cache options
 cache_timeout: 600
 
@@ -158,7 +155,7 @@ cinder_iscsi_port: 3260
 ## Cinder RPC
 cinder_rpc_backend: rabbit
 
-# (StrOpt) Method used to wipe old voumes (valid options are: none, zero,
+# (StrOpt) Method used to wipe old volumes (valid options are: none, zero,
 # shred)
 cinder_volume_clear: shred
 # (StrOpt) The flag to pass to ionice to alter the i/o priority of the process
@@ -187,8 +184,6 @@ cinder_quota_backups: 10
 cinder_quota_backup_gigabytes: 1000
 
 ## General configuration
-## Set this in rpc_user_config.yml UNLESS you want all hosts to use the same
-## Cinder backends.  See the rpc_user_config example for more on how this is done.
 # cinder_backends:
 #   lvm:
 #     volume_group: cinder-volumes
@@ -212,10 +207,8 @@ cinder_quota_backup_gigabytes: 1000
 #  "volume:create": ""
 #  "volume:delete": ""
 
-# Potential locations of glance
-# the variable cinder_glance_api_servers is a list of servers that can service glance
-# by default this variable is undefined
-#cinder_glance_api_servers:
+# Comma separated list of Glance API servers
+# cinder_glance_api_servers:
 
 cinder_glance_host: 127.0.0.1
 cinder_glance_service_port: 9292
@@ -242,7 +235,7 @@ cinder_apt_packages:
 cinder_requires_pip_packages:
   - virtualenv
   - virtualenv-tools
-  - python-keystoneclient # Keystoneclient needed to OSA keystone lib
+  - python-keystoneclient # Keystoneclient needed by the keystone Ansible module
   - httplib2
 
 # Common pip packages

doc/source/index.rst

@@ -1,23 +1 @@
-os_cinder Role Docs
-===================
-
-The os_cinder role is used to to deploy, configure and install OpenStack Block
-Storage.
-
-This role will install the following:
-    * cinder-api
-    * cinder-volume
-    * cinder-scheduler
-
-Basic Role Example
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: yaml
-
-    - name: Installation and setup of cinder
-      hosts: cinder_all
-      user: root
-      roles:
-        - { role: "os_cinder", tags: [ "os-cinder" ] }
-      vars:
-        cinder_galera_address: "{{ internal_lb_vip_address }}"
+.. include:: ../../README.rst