Merge branch 'master' of github.com:boto/boto

3 files changed, 68 insertions, 86 deletions

diff --git a/docs/source/boto_config_tut.rst b/docs/source/boto_config_tut.rst
index 5c517975..76b27b6b 100644
--- a/docs/source/boto_config_tut.rst
+++ b/docs/source/boto_config_tut.rst
@@ -1,34 +1,57 @@
 .. _ref-boto_config:
 
-===============================
+===========
 Boto Config
-===============================
+===========
 
 Introduction
--------------------
-There is a growing list of configuration options for the boto library. Many of these options can be passed into the constructors for top-level objects such as connections. Some options, such as credentials, can also be read from environment variables (e.g. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY). But there is no central place to manage these options. So, the development version of boto has now introduced the notion of boto config files.
+------------
+
+There is a growing list of configuration options for the boto library. Many of
+these options can be passed into the constructors for top-level objects such as
+connections. Some options, such as credentials, can also be read from
+environment variables (e.g. ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``).
+But there is no central place to manage these options. So, the development
+version of boto has now introduced the notion of boto config files.
 
 Details
----------------
-A boto config file is simply a .ini format configuration file that specifies values for options that control the behavior of the boto library. Upon startup, the boto library looks for configuration files in the following locations and in the following order:
+-------
+
+A boto config file is simply a .ini format configuration file that specifies
+values for options that control the behavior of the boto library. Upon startup,
+the boto library looks for configuration files in the following locations
+and in the following order:
+
+* /etc/boto.cfg - for site-wide settings that all users on this machine will use
+* ~/.boto - for user-specific settings
 
-/etc/boto.cfg - for site-wide settings that all users on this machine will use
-~/.boto - for user-specific settings
-The options are merged into a single, in-memory configuration that is available as boto.config. The boto.pyami.config class is a subclass of the standard Python SafeConfigParser object and inherits all of the methods of that object. In addition, the boto.pyami.config class defines additional methods that are described on the PyamiConfigMethods page.
+The options are merged into a single, in-memory configuration that is
+available as :py:mod:`boto.config`. The :py:class:`boto.pyami.config.Config`
+class is a subclass of the standard Python
+:py:class:`ConfigParser.SafeConfigParser` object and inherits all of the
+methods of that object. In addition, the boto
+:py:class:`Config <boto.pyami.config.Config>` class defines additional
+methods that are described on the PyamiConfigMethods page.
 
 Sections
-----------------
-The following sections and options are currently recognized within the boto config file.
+--------
+
+The following sections and options are currently recognized within the
+boto config file.
 
 Credentials
---------------
-The Credentials section is used to specify the AWS credentials used for all boto requests. The order of precedence for authentication credentials is:
+^^^^^^^^^^^
+
+The Credentials section is used to specify the AWS credentials used for all
+boto requests. The order of precedence for authentication credentials is:
+
+* Credentials passed into Connection class constructor.
+* Credentials specified by environment variables
+* Credentials specified as options in the config file.
 
-Credentials passed into Connection class constructor.
-Credentials specified by environment variables
-Credentials specified as options in the config file.
-This section defines the following options:
-aws_access_key_id and aws_secret_access_key. The former being your aws key id and the latter being the secret key.
+This section defines the following options: ``aws_access_key_id`` and
+``aws_secret_access_key``. The former being your aws key id and the latter
+being the secret key.
 
 For example::
 
@@ -36,29 +59,30 @@ For example::
     aws_access_key_id = <your access key>
     aws_secret_access_key = <your secret key>
 
-Please notice that quote characters are not used to either side of the '=' operator even when both your aws access key id and secret key are strings.
+Please notice that quote characters are not used to either side of the '='
+operator even when both your aws access key id and secret key are strings.
 
 Boto
-------
-The Boto section is used to specify options that control the operaton of boto itself. This section defines the following options:
+^^^^
 
-* debug
+The Boto section is used to specify options that control the operaton of
+boto itself. This section defines the following options:
 
-Controls the level of debug messages that will be printed by the boto library. The following values are defined::
+:debug: Controls the level of debug messages that will be printed by the boto library.
+    The following values are defined::
 
         0 - no debug messages are printed
         1 - basic debug messages from boto are printed
         2 - all boto debugging messages plus request/response messages from httplib
 
-* proxy: The name of the proxy host to use for connecting to AWS.
-
-* proxy_port: The port number to use to connect to the proxy host.
-
-* proxy_user: The user name to use when authenticating with proxy host.
-
-* proxy_pass: The password to use when authenticating with proxy host.
-
-* num_retries: The number of times to retry failed requests to an AWS server. If boto receives an error from AWS, it will attempt to recover and retry the request. The default number of retries is 5 but you can change the default with this option.
+:proxy: The name of the proxy host to use for connecting to AWS.
+:proxy_port: The port number to use to connect to the proxy host.
+:proxy_user: The user name to use when authenticating with proxy host.
+:proxy_pass: The password to use when authenticating with proxy host.
+:num_retries: The number of times to retry failed requests to an AWS server.
+  If boto receives an error from AWS, it will attempt to recover and retry the
+  request. The default number of retries is 5 but you can change the default
+  with this option.
 
 As an example::
 
@@ -72,10 +96,15 @@ As an example::
     proxy_pass = bar
 
 Precedence
----------------
-Even if you have your boto config setup, you can also have credentials and options stored in environmental variables or you can explicitly pass them to method calls i.e.::
+----------
+
+Even if you have your boto config setup, you can also have credentials and
+options stored in environmental variables or you can explicitly pass them to
+method calls i.e.::
 
 	>>> boto.connect_ec2('<KEY_ID>','<SECRET_KEY>')
 
-In these cases where these options can be found in more than one place boto will first use the explicitly supplied arguments, if none found it will then look 
-for them amidst environment variables and if that fails it will use the ones in boto config.
+In these cases where these options can be found in more than one place boto
+will first use the explicitly supplied arguments, if none found it will then
+look for them amidst environment variables and if that fails it will use the
+ones in boto config.
diff --git a/docs/source/ec2_tut.rst b/docs/source/ec2_tut.rst
index 40b35516..f8614dbe 100644
--- a/docs/source/ec2_tut.rst
+++ b/docs/source/ec2_tut.rst
@@ -19,13 +19,8 @@ There are two ways to do this in boto.  The first is::
 
 At this point the variable conn will point to an EC2Connection object.  In
 this example, the AWS access key and AWS secret key are passed in to the
-<<<<<<< HEAD
-method explicitely.  Alternatively, you can set the boto config environment
-variables and then call the constructor without any arguments, like this::
-=======
 method explicitely.  Alternatively, you can set the boto config environment variables
 and then call the constructor without any arguments, like this::
->>>>>>> ed64b3aa2a2ad620dc15c87b4b9c5e282bb96dec
 
     >>> conn = EC2Connection()
 
@@ -39,7 +34,6 @@ In either case, conn will point to an EC2Connection object which we will
 use throughout the remainder of this tutorial.
 
 Launching Instances
-<<<<<<< HEAD
 -------------------
 
 Possibly, the most important and common task you'll use EC2 for is to launch,
@@ -69,13 +63,7 @@ For more details on the plethora of possible keyword parameters, be sure to
 check out boto's :doc:`EC2 API reference <ref/ec2>`.
 
 Stopping Instances
-=======
->>>>>>> ed64b3aa2a2ad620dc15c87b4b9c5e282bb96dec
 ------------------
-Possibly, the most important and common task you'll use EC2 for is to launch, stop and terminate instances.
-In its most primitive form, you can launch an instance as follows::
-
-<<<<<<< HEAD
 Once you have your instances up and running, you might wish to shut them down
 if they're not in use. Please note that this will only de-allocate virtual
 hardware resources (as well as instance store drives), but won't destroy your
@@ -85,54 +73,18 @@ even if your instance is stopped. To do this, you can do so as follows::
     >>> conn.stop_instances(instance_ids=['instance-id-1','instance-id-2', ...])
 
 This will request a 'graceful' stop of each of the specified instances. If you
-wish to request the equivalent of unplugging your instance(s),
-simply add force=True keyword argument to the call above. Please note that stop
+wish to request the equivalent of unplugging your instance(s), simply add
+``force=True`` keyword argument to the call above. Please note that stop
 instance is not allowed with Spot instances.
 
 Terminating Instances
 ---------------------
-
 Once you are completely done with your instance and wish to surrender both
 virtual hardware, root EBS volume and all other underlying components
-=======
-    >>> conn.run_instances('<ami-image-id>')
-    
-This will launch an instance in the specified region with the default parameters.
-
-Now, let's say that you already have a key pair, want a specific type of instance, and
-you have your security group all setup. In this case we can use the keyword arguments to accomplish that::
-
-    >>> conn.run_instances('<ami-image-id>',key_name='myKey', instance_type='c1.xlarge', security_groups=['public-facing'])
-
-The main caveat with the above call is that it is possible to request an instance type that is not compatible with the 
-provided AMI (for example, the instance was created for a 64-bit instance and you choose a m1.small instance_type).
-For more details on the plethora of possible keyword parameters, be sure to check out boto's EC2 API documentation_.
-
-.. _documentation: http://boto.cloudhackers.com/en/latest/ref/ec2.html
-
-Stopping Instances
-------------------
-Once you have your instances up and running, you might wish to shut them down if they're not in use. Please note that this will only de-allocate
-virtual hardware resources (as well as instance store drives), but won't destroy your EBS volumes -- this means you'll pay nominal provisioned EBS storage fees 
-even if your instance is stopped. To do this, you can do so as follows::
-
-    >>> conn.stop_instances(instance_ids=['instance-id-1','instance-id-2', ...])
-
-This will request a 'graceful' stop of each of the specified instances. If you wish to request the equivalent of unplugging your instance(s),
-simply add force=True keyword argument to the call above. Please note that stop instance is not allowed with Spot instances.
-
-Terminating Instances
----------------------
-Once you are completely done with your instance and wish to surrender both virtual hardware, root EBS volume and all other underlying components 
->>>>>>> ed64b3aa2a2ad620dc15c87b4b9c5e282bb96dec
 you can request instance termination. To do so you can use the call bellow::
 
     >>> conn.terminate_instances(instance_ids=['instance-id-1','instance-id-2', ...])
 
-<<<<<<< HEAD
 Please use with care since once you request termination for an instance there
 is no turning back.
-=======
-Please use with care since once you request termination for an instance there is not turning back.
->>>>>>> ed64b3aa2a2ad620dc15c87b4b9c5e282bb96dec
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4eac7452..264d3d49 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -115,6 +115,7 @@ Additional Resources
    s3_tut
    ref/s3
    ref/mturk
+   boto_config_tut
    ref/index
    documentation