Restructure docs a bit; add getting started docs

docs/getting_started.rst

@@ -1,82 +1,102 @@
 Getting Started
 ===============
+This getting started guide will provide a quick tour of some Cloudbridge
+features. For more details on individual features, see the
+`Using Cloudbridge <topics/overview.html>`_ section or the
+`API reference <api_docs/ref.html>`_.
 
-This getting started guide will provide a quick tour of some cloud bridge
-features. You should reach the conceptual structure section to get a quick
-idea of the main types of objects that cloudbridge provides.
+Installation
+------------
+Cloudbridge is available on PyPI so to install the latest available version,
+run::
 
-Creating a provider
--------------------
-
-To initialize a connection to a cloud and get a provider object, you will
-need to provide the cloud's access credentials to cloudbridge. These may
-be provided in one of two ways.
-
-1. Environment variables
-2. A dictionary
-
-Providing access credentials through environment variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    pip install cloudbridge
 
-When initializing a provider through environment variables,  you can
-create a connection as follows.
+Create a provider
+-----------------
+To start, you will need to create a reference to a provider object. The
+provider object idetifies the cloud you want to work with and supplies your
+credentials. In this code snippet, we will be using AWS. For the details on
+other providers, take a look at the `Setup page <topics/setup.html>`_.
 
 .. code-block:: python
 
-	from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
-
-	provider = CloudProviderFactory().create_provider(ProviderList.OPENSTACK, {})
-
-The following environment variables must be set, depending on the provider in use.
-
-**Amazon**
+    from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
 
-*Mandatory variables*::
+    config = {'aws_access_key': 'AKIAJW2XCYO4AF55XFEQ',
+              'aws_secret_key': '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'}
+    provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)
 
-	AWS_ACCESS_KEY
-	AWS_SECRET_KEY
-
-**Openstack**
+List some resources
+-------------------
+Once you have a reference to a provider, explore the cloud platform:
 
-*Mandatory variables*::
+.. code-block:: python
 
-	OS_AUTH_URL
-	OS_USERNAME
-	OS_PASSWORD
-	OS_TENANT_NAME
-	OS_REGION_NAME
+    provider.compute.images.list()
+    provider.security.security_groups.list()
+    provider.block_store.snapshots.list()
+    provider.object_store.list()
 
-*Optional variables*::
+This will demonstrate the fact the library was properly installed and your
+provider object is setup corectly but it is not very interesting. Hence, let's
+create a new instance we can ssh into using a key pair.
 
-	NOVA_SERVICE_NAME
-	OS_COMPUTE_API_VERSION
-	OS_VOLUME_API_VERSION
+Create a key pair
+-----------------
+We'll create a new key pair and save the private portion of the key to a file
+on disc as a read-only file.
 
+.. code-block:: python
 
-Providing access credentials through a dictionary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    kp = provider.security.key_pairs.create('cloudbridge_intro')
+    with open('cloudbridge_intro.pem', 'w') as f:
+        f.write(kp.material)
+    import os
+    os.chmod('cloudbridge_intro.pem', 0400)
 
-You can initialize a simple config as follows. The key names are the same
-as the environment variables, in lower case. Note that the config dictionary
-will override environment values.
+Create a security group
+-----------------------
+Next, we need to create a security group and add a rule to allow ssh access.
 
 .. code-block:: python
 
-	from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
+    sg = provider.security.security_groups.create(
+        'cloudbridge_intro', 'A security group used by Cloudbridge')
+    sg.add_rule('tcp', 22, 22, '0.0.0.0/0')
 
-	config = {'aws_access_key' : '<your_access_key>',
-			  'aws_secret_key' : '<your_secret_key>'}
-	provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)
+Launch an instance
+------------------
+Before we can launch an instance, we need to decide what image to use so let's
+get the default Ubuntu image ``ami-d05e75b8`` and launch an instance.
 
-Launching a new instance
-________________________
+.. code-block:: python
 
+    img = provider.compute.images.get('ami-d05e75b8')
+    inst_type = provider.compute.instance_types.list()[34]  # c3.large
+    inst = provider.compute.instances.create(
+        name='Cloudbridge-intro', image=img, instance_type=inst_type,
+        keypair=kp, security_groups=[sg])
+    # Refresh the state
+    inst.refresh()
+    inst.state
+    # 'running'
+    inst.public_ips
+    # [u'54.166.125.219']
+
+From the command prompt, we can now ssh into the instance
+``ssh -i cloudbridge_intro.pem ubuntu@54.166.125.219``.
+
+Cleanup
+-------
+To wrap things up, let's clean up all the resources we have created
 
-Common methods
-______________
+.. code-block:: python
 
-create
-list
-find
-delete
+    inst.terminate()
+    sg.delete()
+    kp.delete()
 
+And that's it - a full circle in a few lines of code. For homework, try to do
+the same but with a different provider. All you will need to change is the
+cloud-specific data, namely the provider setup and the image ID.

docs/index.rst

@@ -39,32 +39,19 @@ that they return. Click on any object to drill down into its details.
 Installation
 ------------
 
-**Automatic installation**::
+The latest release can always be installed form PyPI. For other installation
+options, see the `installation page <topics/install.html>`_::
 
     pip install cloudbridge
 
-**Manual installation**::
-
-	$ git clone https://github.com/gvlproject/cloudbridge.git
-	$ cd cloudbridge
-	$ python setup.py install
-
-**Developer installation**::
-
-	pip install cloudbridge[dev]
-
-This will install additional libraries required by cloudbridge contributors, such as tox.
-
-**Prerequisites**: Cloudbridge runs on Python 2.7 and higher. Python 3 is recommended.
-
-
 Documentation
 -------------
 .. toctree::
     :maxdepth: 2
 
     concepts.rst
     getting_started.rst
+    topics/overview.rst
     api_docs/ref.rst
 
 Page index

docs/topics/install.rst

@@ -0,0 +1,21 @@
+Installation
+============
+
+**Latest release**::
+
+    pip install cloudbridge
+
+**Manual installation**::
+
+    $ git clone https://github.com/gvlproject/cloudbridge.git
+    $ cd cloudbridge
+    $ python setup.py install
+
+**Developer installation**::
+
+    pip install cloudbridge[dev]
+
+This will install additional libraries required by cloudbridge contributors, such as tox.
+
+**Prerequisites**: Cloudbridge runs on Python 2.7 and higher. Python 3 is recommended.
+

docs/topics/overview.rst

@@ -0,0 +1,8 @@
+Using Cloudbridge
+=================
+Introductions to all the key parts of Cloudbridge you'll need to know:
+
+- `How to install Cloudbridge <install.html>`_
+- `Connection and authentication setup <setup.html>`_
+
+

docs/topics/setup.rst

@@ -0,0 +1,58 @@
+Setup
+-----
+To initialize a connection to a cloud and get a provider object, you will
+need to provide the cloud's access credentials to Cloudbridge. These may
+be provided in one of two ways:
+
+1. Environment variables
+2. A dictionary
+
+Providing access credentials through environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following environment variables must be set, depending on the provider in use.
+
+**Amazon**
+
+*Mandatory variables*::
+
+    AWS_ACCESS_KEY
+    AWS_SECRET_KEY
+
+**Openstack**
+
+*Mandatory variables*::
+
+    OS_AUTH_URL
+    OS_USERNAME
+    OS_PASSWORD
+    OS_TENANT_NAME
+    OS_REGION_NAME
+
+*Optional variables*::
+
+    NOVA_SERVICE_NAME
+    OS_COMPUTE_API_VERSION
+    OS_VOLUME_API_VERSION
+
+Once the environment variables are set, you can create a connection as follows:
+
+.. code-block:: python
+
+    from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
+
+    provider = CloudProviderFactory().create_provider(ProviderList.OPENSTACK, {})
+
+
+Providing access credentials through a dictionary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can initialize a simple config as follows. The key names are the same
+as the environment variables, in lower case. Note that the config dictionary
+will override environment values.
+
+.. code-block:: python
+
+    from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
+
+    config = {'aws_access_key' : '<your_access_key>',
+              'aws_secret_key' : '<your_secret_key>'}
+    provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)