Add more block storage docs

docs/topics/block_storage.rst

@@ -10,10 +10,52 @@ from it.
 Volume storage
 --------------
 Operations, such as creating a new volume and listing the existing ones, are
-performed via the :class:`.VolumeService`.
+performed via the :class:`.VolumeService`. To start, let's create a 1GB volume.
 
 .. code-block:: python
 
-    vol = provider.block_store.volumes.create('Cloudbridge-vol', 1, 'us-east-1a')
+    vol = provider.block_store.volumes.create('Cloudbridge-vol', 1, 'us-east-1e')
     vol.wait_till_ready()
     provider.block_store.volumes.list()
+
+Next, let's attach the volume to a running instance as device ``/dev/sdh``::
+
+    vol.attach('i-dbf37022', '/dev/sdh')
+    vol.refresh()
+    vol.state
+    # 'in-use'
+
+Once attached, from within the instance, it is necessary to create a file
+system on the new volume and mount it.
+
+Once you wish to detach a volume from an instance, it is necessary to unmount
+the file system from within the instance and detach it. The volume can then be
+attached to a different instance with all the data on it preserved.
+
+.. code-block:: python
+
+    vol.detach()
+    vol.refresh()
+    vol.state
+    # 'available'
+
+Snapshot storage
+----------------
+A volume snapshot it created from an existing volume. Note that it may take a
+long time for a snapshot to become ready, particularly on AWS.
+
+.. code-block:: python
+
+    snap = vol.create_snapshot('cloudbridge-snap',
+                               'A demo snapshot created via Cloudbridge.')
+    snap.wait_till_ready()
+    snap.state
+    # 'available'
+
+In order to make use of a snapshot, it is necessary to create a volume from it::
+
+    vol = provider.block_store.volumes.create(
+        'Cloudbridge-snap-vol', 1, 'us-east-1e', snapshot=snap)
+
+The newly created volume behaves just like any other volume and can be attached
+to an instance for use.