Updated docs: Added conceptual overview, and getting started.

docs/concepts.rst

@@ -0,0 +1,43 @@
+Concepts and Organisation
+=========================
+
+Conceptually, cloudbridge consists of the following types of objects.
+
+1. Providers - Represents a connection to a cloud provider, and is
+the gateway to using its services.
+
+2. Services - Represents a service provided by a cloud provider,
+such as its compute service, block storage service, object storage etc.
+Services may in turn be divided into smaller services. Smaller services
+tend to have uniform methods, such as create, find and list. For example,
+InstanceService.list(), InstanceService.find() etc. which can be used
+to access cloud resources. Larger services tend to provide organisational
+structure only. For example, the block store service provides access to
+the VolumeService and SnapshotService.
+
+3. Resources - resources are objects returned by a service,
+and represent a remote resource. For example, InstanceService.list()
+will return a list of Instance objects, which can be used to manipulate
+an instance. Similarly, VolumeService.create() will return a Volume object.
+
+
+.. image:: images/object_relationships_overview.svg
+
+The actual source code structure of cloudbridge also mirrors this organisation.
+
+Detailed class relationships
+----------------------------
+
+The following diagram shows a typical provider object graph and the relationship
+between services.
+
+.. image:: images/object_relationships_detailed.svg
+
+Some services are nested. For example, to access the instance service, you can
+use `provider.compute.instances`. Similarly, to get a list of all instances,
+you can use the following code.
+
+.. code-block:: python
+
+	instances = provider.compute.instances.list()
+	print(instances[0].name)

docs/getting_started.rst

@@ -0,0 +1,82 @@
+Getting Started
+===============
+
+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.
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When initializing a provider through environment variables,  you can
+create a connection as follows.
+
+.. 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**
+
+*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
+
+
+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)
+
+Launching a new instance
+________________________
+
+
+Common methods
+______________
+
+create
+list
+find
+delete
+

docs/index.rst

@@ -1,4 +1,4 @@
-.. cloudbridge documentation master file, created by
+	.. cloudbridge documentation master file, created by
    sphinx-quickstart on Sat Oct 10 03:17:52 2015.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -6,11 +6,12 @@
 Welcome to cloudbridge's documentation!
 =======================================
 
-cloudbridge provides a layer of abstraction over different cloud providers.
-It's a straightforward implementation of the `bridge pattern`_.
+cloudbridge aims to provide a simple layer of abstraction over
+different cloud providers, reducing or eliminating the need to write
+conditional code for each cloud.
 
 Usage example
-~~~~~~~~~~~~~
+-------------
 
 The simplest possible example for doing something useful with cloudbridge would
 look like the following.
@@ -20,20 +21,43 @@ look like the following.
 	from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
 
 	provider = CloudProviderFactory().create_provider(ProviderList.AWS, {})
-	print(provider.security.key_pairs.list())
+	print(provider.compute.instances.list())
 
 In the example above, the AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables
 must be set to your cloud credentials.
 
+Installation
+------------
+
+**Automatic installation**::
+
+    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
     api_docs/ref.rst
 
 Page index
-~~~~~~~~~~
+----------
 * :ref:`genindex`
 
-.. _`bridge pattern`: https://en.wikipedia.org/wiki/Bridge_pattern

setup.py

@@ -5,7 +5,7 @@ openstack_reqs = ['python-novaclient', 'python-cinderclient',
                   'python-swiftclient', 'python-neutronclient']
 aws_reqs = ['boto']
 full_reqs = base_reqs + aws_reqs + openstack_reqs
-dev_reqs = ['tox', 'moto>=0.4.18'] + full_reqs
+dev_reqs = ['tox', 'moto>=0.4.18', 'sphinx'] + full_reqs
 
 setup(name='cloudbridge',
       version=0.1,