docs: make the first example easier to understand

The very first example of the usage of shade is easier to understand
if there is also an example of the needed `clouds.yml` file. Without
it, it is unclear what the meaning of the key `mordred` means.

Change-Id: Iad3aba66b0c6344157da30f374e191d01e938b2b

README.rst

@@ -21,7 +21,29 @@ Example
 =======
 
 Sometimes an example is nice.
-::
+
+#. Create a ``clouds.yml`` file::
+
+     clouds:
+      mordred:
+        region_name: RegionOne
+        auth:
+          username: 'mordred'
+          password: XXXXXXX
+          project_name: 'shade'
+          auth_url: 'https://montytaylor-sjc.openstack.blueboxgrid.com:5001/v2.0'
+
+   Please note: *os-client-config* will look for a file called ``clouds.yaml``
+   in the following locations:
+
+   * Current Directory
+   * ``~/.config/openstack``
+   * ``/etc/openstack``
+
+   More information at https://pypi.python.org/pypi/os-client-config
+
+
+#. Create a server with *shade*, configured with the ``clouds.yml`` file::
 
     import shade
 
@@ -43,3 +65,4 @@ Sometimes an example is nice.
     # to get a public ip for it.
     cloud.create_server(
         'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
+