Adds notes about installation, remove doc build warnings

Kevin McDonald · Kevin McDonald · commit 7986872381f0 · 2015-08-14T15:24:49.000-05:00
diff --git a/SoftLayer/managers/hardware.py b/SoftLayer/managers/hardware.py
@@ -21,11 +21,6 @@
 class HardwareManager(utils.IdentifierMixin, object):
     """Manage hardware devices.
 
-    :param SoftLayer.API.Client client: an API client instance
-    :param SoftLayer.managers.OrderingManager ordering_manager: an optional
-                                              manager to handle ordering.
-                                              If none is provided, one will be
-                                              auto initialized.
     Example::
 
        # Initialize the Manager.
@@ -36,6 +31,12 @@ class HardwareManager(utils.IdentifierMixin, object):
        import SoftLayer
        client = SoftLayer.Client()
        mgr = SoftLayer.HardwareManager(client)
+
+    :param SoftLayer.API.Client client: an API client instance
+    :param SoftLayer.managers.OrderingManager ordering_manager: an optional
+                                              manager to handle ordering.
+                                              If none is provided, one will be
+                                              auto initialized.
     """
     def __init__(self, client, ordering_manager=None):
         self.client = client
@@ -51,15 +52,16 @@ def cancel_hardware(self, hardware_id, reason='unneeded', comment='',
                         immediate=False):
         """Cancels the specified dedicated server.
 
+        Example::
+
+            # Cancels hardware id 1234
+            result = mgr.cancel_hardware(hardware_id=1234)
+
         :param int hardware_id: The ID of the hardware to be cancelled.
         :param string reason: The reason code for the cancellation. This should
                               come from :func:`get_cancellation_reasons`.
         :param string comment: An optional comment to include with the
                                cancellation.
-        Example::
-
-            # Cancels hardware id 1234
-            result = mgr.cancel_hardware(hardware_id=1234)
         """
 
         # Get cancel reason
diff --git a/SoftLayer/managers/vs.py b/SoftLayer/managers/vs.py
@@ -53,6 +53,18 @@ def list_instances(self, hourly=True, monthly=True, tags=None, cpus=None,
                        public_ip=None, private_ip=None, **kwargs):
         """Retrieve a list of all virtual servers on the account.
 
+        Example::
+
+            # Print out a list of hourly instances in the DAL05 data center.
+
+            for vsi in mgr.list_instances(hourly=True, datacenter='dal05'):
+               print vsi['fullyQualifiedDomainName'], vsi['primaryIpAddress']
+
+            # Using a custom object-mask. Will get ONLY what is specified
+            object_mask = "mask[hostname,monitoringRobot[robotStatus]]"
+            for vsi in mgr.list_instances(mask=object_mask,hourly=True):
+                print vsi
+
         :param boolean hourly: include hourly instances
         :param boolean monthly: include monthly instances
         :param list tags: filter based on list of tags
@@ -68,19 +80,6 @@ def list_instances(self, hourly=True, monthly=True, tags=None, cpus=None,
         :param dict \\*\\*kwargs: response-level options (mask, limit, etc.)
         :returns: Returns a list of dictionaries representing the matching
                   virtual servers
-
-        Example::
-
-            # Print out a list of hourly instances in the DAL05 data center.
-
-            for vsi in mgr.list_instances(hourly=True, datacenter='dal05'):
-               print vsi['fullyQualifiedDomainName'], vsi['primaryIpAddress']
-
-            # Using a custom object-mask. Will get ONLY what is specified
-            object_mask = "mask[hostname,monitoringRobot[robotStatus]]"
-            for vsi in mgr.list_instances(mask=object_mask,hourly=True):
-                print vsi
-
         """
         if 'mask' not in kwargs:
             items = [
@@ -463,6 +462,32 @@ def verify_create_instance(self, **kwargs):
     def create_instance(self, **kwargs):
         """Creates a new virtual server instance.
 
+        .. warning::
+
+            This will add charges to your account
+
+        Example::
+
+            new_vsi = {
+                'domain': u'test01.labs.sftlyr.ws',
+                'hostname': u'minion05',
+                'datacenter': u'hkg02',
+                'dedicated': False,
+                'private': False,
+                'cpus': 1,
+                'os_code' : u'UBUNTU_LATEST',
+                'hourly': True,
+                'ssh_keys': [1234],
+                'disks': ('100','25'),
+                'local_disk': True,
+                'memory': 1024,
+                'tags': 'test, pleaseCancel'
+            }
+
+            vsi = mgr.create_instance(**new_vsi)
+            # vsi will have the newly created vsi details if done properly.
+            print vsi
+
         :param int cpus: The number of virtual CPUs to include in the instance.
         :param int memory: The amount of RAM to order.
         :param bool hourly: Flag to indicate if this server should be billed
@@ -492,30 +517,6 @@ def create_instance(self, **kwargs):
         :param list ssh_keys: The SSH keys to add to the root user
         :param int nic_speed: The port speed to set
         :param string tags: tags to set on the VS as a comma separated list
-
-        .. warning::
-            This will add charges to your account
-
-        Example::
-            new_vsi = {
-                'domain': u'test01.labs.sftlyr.ws',
-                'hostname': u'minion05',
-                'datacenter': u'hkg02',
-                'dedicated': False,
-                'private': False,
-                'cpus': 1,
-                'os_code' : u'UBUNTU_LATEST',
-                'hourly': True,
-                'ssh_keys': [1234],
-                'disks': ('100','25'),
-                'local_disk': True,
-                'memory': 1024,
-                'tags': 'test, pleaseCancel'
-            }
-
-            vsi = mgr.create_instance(**new_vsi)
-            # vsi will have the newly created vsi details if done properly.
-            print vsi
         """
         tags = kwargs.pop('tags', None)
         inst = self.guest.createObject(self._generate_create_dict(**kwargs))
@@ -530,9 +531,11 @@ def create_instances(self, config_list):
         create_instance().
 
         .. warning::
+
             This will add charges to your account
 
         Example::
+
             # Define the instance we want to create.
             new_vsi = {
                 'domain': u'test01.labs.sftlyr.ws',
@@ -576,6 +579,13 @@ def create_instances(self, config_list):
     def change_port_speed(self, instance_id, public, speed):
         """Allows you to change the port speed of a virtual server's NICs.
 
+        Example::
+
+            #change the Public interface to 10Mbps on instance 12345
+            result = mgr.change_port_speed(instance_id=12345,
+                                        public=True, speed=10)
+            # result will be True or an Exception
+
         :param int instance_id: The ID of the VS
         :param bool public: Flag to indicate which interface to change.
                             True (default) means the public interface.
@@ -584,12 +594,6 @@ def change_port_speed(self, instance_id, public, speed):
 
         .. warning::
             A port speed of 0 will disable the interface.
-
-        Example::
-            #change the Public interface to 10Mbps on instance 12345
-            result = mgr.change_port_speed(instance_id=12345,
-                                        public=True, speed=10)
-            # result will be True or an Exception
         """
         if public:
             func = self.guest.setPublicNetworkInterfaceSpeed
@@ -711,14 +715,6 @@ def upgrade(self, instance_id, cpus=None, memory=None,
                 nic_speed=None, public=True):
         """Upgrades a VS instance.
 
-        :param int instance_id: Instance id of the VS to be upgraded
-        :param int cpus: The number of virtual CPUs to upgrade to
-                            of a VS instance.
-        :param bool public: CPU will be in Private/Public Node.
-        :param int memory: RAM of the VS to be upgraded to.
-        :param int nic_speed: The port speed to set
-
-        :returns: bool
         Example::
 
            # Upgrade instance 12345 to 4 CPUs and 4 GB of memory
@@ -727,6 +723,14 @@ def upgrade(self, instance_id, cpus=None, memory=None,
            mgr = SoftLayer.VSManager(client)
            mgr.upgrade(12345, cpus=4, memory=4)
 
+        :param int instance_id: Instance id of the VS to be upgraded
+        :param int cpus: The number of virtual CPUs to upgrade to
+                            of a VS instance.
+        :param bool public: CPU will be in Private/Public Node.
+        :param int memory: RAM of the VS to be upgraded to.
+        :param int nic_speed: The port speed to set
+
+        :returns: bool
         """
         package_items = self._get_package_items()
         prices = []
diff --git a/docs/install.rst b/docs/install.rst
@@ -3,6 +3,13 @@
 Installation
 ============
 
+What's Included
+---------------
+When you install softlayer-python you you will get the following:
+
+* a python package called 'SoftLayer' (casing is important) available in your python path.
+* a command-line client placed in your system path named 'slcli'.
+
 Using Pip
 ---------
 
