Merge pull request #920 from allmightyspiff/doc_updates

Doc updates

Author: allmightyspiff

SoftLayer/managers/block.py

@@ -408,8 +408,7 @@ def cancel_snapshot_space(self, volume_id,
 
         :param integer volume_id: The volume ID
         :param string reason: The reason for cancellation
-        :param boolean immediate_flag: Cancel immediately or
-        on anniversary date
+        :param boolean immediate_flag: Cancel immediately or on anniversary date
         """
 
         block_volume = self.get_block_volume_details(
@@ -506,8 +505,7 @@ def cancel_block_volume(self, volume_id,
 
         :param integer volume_id: The volume ID
         :param string reason: The reason for cancellation
-        :param boolean immediate_flag: Cancel immediately or
-        on anniversary date
+        :param boolean immediate_flag: Cancel immediately or on anniversary date
         """
         block_volume = self.get_block_volume_details(
             volume_id,

SoftLayer/managers/dedicated_host.py

@@ -1,6 +1,6 @@
 """
     SoftLayer.dedicatedhost
-    ~~~~~~~~~~~~
+    ~~~~~~~~~~~~~~~~~~~~~~~
     DH Manager/helpers
 
     :license: MIT, see License for more details.
@@ -23,21 +23,10 @@ class DedicatedHostManager(utils.IdentifierMixin, object):
 
         See product information here https://www.ibm.com/cloud/dedicated
 
-        Example::
-            # Initialize the DedicatedHostManager.
-            # env variables. These can also be specified in ~/.softlayer,
-            # or passed directly to SoftLayer.Client()
-            # SL_USERNAME = YOUR_USERNAME
-            # SL_API_KEY = YOUR_API_KEY
-            import SoftLayer
-            client = SoftLayer.Client()
-            mgr = SoftLayer.DedicatedHostManager(client)
 
     :param SoftLayer.API.BaseClient client: the client instance
-    :param SoftLayer.managers.OrderingManager ordering_manager: an optional
-                                              manager to handle ordering.
-                                              If none is provided, one will be
-                                              auto initialized.
+    :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):
@@ -52,19 +41,14 @@ def list_instances(self, tags=None, cpus=None, memory=None, hostname=None,
                        disk=None, datacenter=None, **kwargs):
         """Retrieve a list of all dedicated hosts on the account
 
-        Example::
-
         :param list tags: filter based on list of tags
         :param integer cpus: filter based on number of CPUS
         :param integer memory: filter based on amount of memory
         :param string hostname: filter based on hostname
         :param string disk: filter based on disk
         :param string datacenter: filter based on datacenter
         :param dict \\*\\*kwargs: response-level options (mask, limit, etc.)
-        :returns: Returns a list of dictionaries representing the matching
-                  dedicated host.
-
-
+        :returns: Returns a list of dictionaries representing the matching dedicated host.
 
         """
         if 'mask' not in kwargs:
@@ -113,8 +97,7 @@ def get_host(self, host_id, **kwargs):
         """Get details about a dedicated host.
 
         :param integer : the host ID
-        :returns: A dictionary containing a large amount of information about
-                  the specified instance.
+        :returns: A dictionary containing host information.
 
         Example::
 

SoftLayer/managers/file.py

@@ -357,21 +357,16 @@ def create_snapshot(self, volume_id, notes='', **kwargs):
         return self.client.call('Network_Storage', 'createSnapshot',
                                 notes, id=volume_id, **kwargs)
 
-    def enable_snapshots(self, volume_id, schedule_type, retention_count,
-                         minute, hour, day_of_week, **kwargs):
+    def enable_snapshots(self, volume_id, schedule_type, retention_count, minute, hour, day_of_week, **kwargs):
         """Enables snapshots for a specific file volume at a given schedule
 
         :param integer volume_id: The id of the volume
         :param string schedule_type: 'HOURLY'|'DAILY'|'WEEKLY'
-        :param integer retention_count: The number of snapshots to attempt to
-        retain in this schedule
-        :param integer minute: The minute of the hour at which HOURLY, DAILY,
-        and WEEKLY snapshots should be taken
-        :param integer hour: The hour of the day at which DAILY and WEEKLY
-        snapshots should be taken
-        :param string|integer day_of_week: The day of the week on which WEEKLY
-        snapshots should be taken, either as a string ('SUNDAY') or integer
-        ('0' is Sunday)
+        :param integer retention_count: The number of snapshots to attempt to retain in this schedule
+        :param integer minute: The minute of the hour at which HOURLY, DAILY, and WEEKLY snapshots should be taken
+        :param integer hour: The hour of the day at which DAILY and WEEKLY snapshots should be taken
+        :param string|integer day_of_week: The day of the week on which WEEKLY snapshots should be taken,
+                              either as a string ('SUNDAY') or integer ('0' is Sunday)
         :return: Returns whether successfully scheduled or not
         """
 
@@ -392,8 +387,7 @@ def disable_snapshots(self, volume_id, schedule_type):
         :return: Returns whether successfully disabled or not
         """
 
-        return self.client.call('Network_Storage', 'disableSnapshots',
-                                schedule_type, id=volume_id)
+        return self.client.call('Network_Storage', 'disableSnapshots', schedule_type, id=volume_id)
 
     def list_volume_schedules(self, volume_id):
         """Lists schedules for a given volume
@@ -409,8 +403,7 @@ def list_volume_schedules(self, volume_id):
 
         return utils.lookup(volume_detail, 'schedules')
 
-    def order_snapshot_space(self, volume_id, capacity, tier,
-                             upgrade, **kwargs):
+    def order_snapshot_space(self, volume_id, capacity, tier, upgrade, **kwargs):
         """Orders snapshot space for the given file volume.
 
         :param integer volume_id: The ID of the volume
@@ -431,15 +424,12 @@ def order_snapshot_space(self, volume_id, capacity, tier,
 
         return self.client.call('Product_Order', 'placeOrder', order)
 
-    def cancel_snapshot_space(self, volume_id,
-                              reason='No longer needed',
-                              immediate=False):
+    def cancel_snapshot_space(self, volume_id, reason='No longer needed', immediate=False):
         """Cancels snapshot space for a given volume.
 
         :param integer volume_id: The volume ID
         :param string reason: The reason for cancellation
-        :param boolean immediate: Cancel immediately or
-        on anniversary date
+        :param boolean immediate: Cancel immediately or on anniversary date
         """
 
         file_volume = self.get_file_volume_details(
@@ -482,15 +472,12 @@ def restore_from_snapshot(self, volume_id, snapshot_id):
         return self.client.call('Network_Storage', 'restoreFromSnapshot',
                                 snapshot_id, id=volume_id)
 
-    def cancel_file_volume(self, volume_id,
-                           reason='No longer needed',
-                           immediate=False):
+    def cancel_file_volume(self, volume_id, reason='No longer needed', immediate=False):
         """Cancels the given file storage volume.
 
         :param integer volume_id: The volume ID
         :param string reason: The reason for cancellation
-        :param boolean immediate: Cancel immediately or
-        on anniversary date
+        :param boolean immediate: Cancel immediately or on anniversary date
         """
         file_volume = self.get_file_volume_details(
             volume_id,

SoftLayer/managers/ordering.py

@@ -11,29 +11,14 @@
 
 CATEGORY_MASK = '''id,
                    isRequired,
-                   itemCategory[
-                     id,
-                     name,
-                     categoryCode
-                   ]
+                   itemCategory[id, name, categoryCode]
                 '''
 
-ITEM_MASK = '''id,
-               keyName,
-               description
-            '''
+ITEM_MASK = '''id, keyName, description'''
 
-PACKAGE_MASK = '''id,
-                  name,
-                  keyName,
-                  isActive
-               '''
+PACKAGE_MASK = '''id, name, keyName, isActive'''
 
-PRESET_MASK = '''id,
-                 name,
-                 keyName,
-                 description
-              '''
+PRESET_MASK = '''id, name, keyName, description'''
 
 
 class OrderingManager(object):
@@ -102,7 +87,7 @@ def get_only_active_packages(packages):
         If a package is active, it is eligible for ordering
         This will inspect the 'isActive' property on the provided packages
 
-        :param packages Dictionary of packages, isActive key must be present
+        :param packages: Dictionary of packages, isActive key must be present
         """
 
         active_packages = []
@@ -121,8 +106,7 @@ def get_package_by_type(self, package_type, mask=None):
         one returned by the API.
         If no packages are found, returns None
 
-        :param package_type string representing the package type key name
-                            we are interested in
+        :param string package_type: representing the package type key name we are interested in
         """
         packages = self.get_packages_of_type([package_type], mask)
         if len(packages) == 0:
@@ -133,9 +117,8 @@ def get_package_by_type(self, package_type, mask=None):
     def get_package_id_by_type(self, package_type):
         """Return the package ID of a Product Package with a given type.
 
-        :param package_type string representing the package type key name
-                            we are interested in
-        :raises ValueError when no package of the given type is found
+        :param string package_type: representing the package type key name we are interested in
+        :raises ValueError: when no package of the given type is found
         """
 
         mask = "mask[id, name, description, isActive, type[keyName]]"
@@ -148,7 +131,7 @@ def get_package_id_by_type(self, package_type):
     def get_quotes(self):
         """Retrieve a list of quotes.
 
-        :return a list of SoftLayer_Billing_Order_Quote
+        :returns: a list of SoftLayer_Billing_Order_Quote
         """
 
         quotes = self.client['Account'].getActiveQuotes()
@@ -157,7 +140,7 @@ def get_quotes(self):
     def get_quote_details(self, quote_id):
         """Retrieve quote details.
 
-        :param quote_id ID number of target quote
+        :param quote_id: ID number of target quote
         """
 
         quote = self.client['Billing_Order_Quote'].getObject(id=quote_id)
@@ -166,7 +149,7 @@ def get_quote_details(self, quote_id):
     def get_order_container(self, quote_id):
         """Generate an order container from a quote object.
 
-        :param quote_id ID number of target quote
+        :param quote_id: ID number of target quote
         """
 
         quote = self.client['Billing_Order_Quote']
@@ -196,8 +179,7 @@ def generate_order_template(self, quote_id, extra, quantity=1):
             product_type = 'hardware'
 
         if len(extra) != quantity:
-            raise ValueError("You must specify extra for each server in the "
-                             "quote")
+            raise ValueError("You must specify extra for each server in the quote")
 
         container[product_type] = []
         for extra_details in extra:
@@ -236,8 +218,7 @@ def get_package_by_key(self, package_keyname, mask=None):
 
         If no packages are found, returns None
 
-        :param package_keyname string representing the package key name
-                            we are interested in.
+        :param package_keyname: string representing the package key name we are interested in.
         :param string mask: Mask to specify the properties we want to retrieve
         """
         _filter = {
@@ -394,16 +375,15 @@ def verify_order(self, package_keyname, location, item_keynames, complex_type=No
                                    possible keynames for a package, use list_items()
                                    (or `slcli order item-list`)
         :param str complex_type: The complex type to send with the order. Typically begins
-                                 with 'SoftLayer_Container_Product_Order_'.
+                                 with `SoftLayer_Container_Product_Order_`.
         :param bool hourly: If true, uses hourly billing, otherwise uses monthly billing
         :param string preset_keyname: If needed, specifies a preset to use for that package.
                                       To see a list of possible keynames for a package, use
                                       list_preset() (or `slcli order preset-list`)
         :param dict extras: The extra data for the order in dictionary format.
                             Example: A VSI order requires hostname and domain to be set, so
                             extras will look like the following:
-                                {'virtualGuests': [{'hostname': 'test',
-                                                    'domain': 'softlayer.com'}]}
+                            'virtualGuests': [{'hostname': 'test', 'domain': 'softlayer.com'}]}
         :param int quantity: The number of resources to order
 
         """
@@ -425,16 +405,15 @@ def place_order(self, package_keyname, location, item_keynames, complex_type=Non
                                    possible keynames for a package, use list_items()
                                    (or `slcli order item-list`)
         :param str complex_type: The complex type to send with the order. Typically begins
-                                 with 'SoftLayer_Container_Product_Order_'.
+                                 with `SoftLayer_Container_Product_Order_`.
         :param bool hourly: If true, uses hourly billing, otherwise uses monthly billing
         :param string preset_keyname: If needed, specifies a preset to use for that package.
                                       To see a list of possible keynames for a package, use
                                       list_preset() (or `slcli order preset-list`)
         :param dict extras: The extra data for the order in dictionary format.
                             Example: A VSI order requires hostname and domain to be set, so
                             extras will look like the following:
-                                {'virtualGuests': [{'hostname': 'test',
-                                                    'domain': 'softlayer.com'}]}
+                            {'virtualGuests': [{'hostname': 'test', domain': 'softlayer.com'}]}
         :param int quantity: The number of resources to order
 
         """
@@ -457,16 +436,15 @@ def generate_order(self, package_keyname, location, item_keynames, complex_type=
                                    possible keynames for a package, use list_items()
                                    (or `slcli order item-list`)
         :param str complex_type: The complex type to send with the order. Typically begins
-                                 with 'SoftLayer_Container_Product_Order_'.
+                                 with `SoftLayer_Container_Product_Order_`.
         :param bool hourly: If true, uses hourly billing, otherwise uses monthly billing
         :param string preset_keyname: If needed, specifies a preset to use for that package.
                                       To see a list of possible keynames for a package, use
                                       list_preset() (or `slcli order preset-list`)
         :param dict extras: The extra data for the order in dictionary format.
                             Example: A VSI order requires hostname and domain to be set, so
                             extras will look like the following:
-                                {'virtualGuests': [{'hostname': 'test',
-                                                    'domain': 'softlayer.com'}]}
+                            {'virtualGuests': [{'hostname': 'test', 'domain': 'softlayer.com'}]}
         :param int quantity: The number of resources to order
 
         """

docs/api/managers/block.rst

@@ -0,0 +1,5 @@
+.. _block:
+
+.. automodule:: SoftLayer.managers.block
+   :members:
+   :inherited-members:

docs/api/managers/dedicated_host.rst

@@ -0,0 +1,5 @@
+.. _dedicated_host:
+
+.. automodule:: SoftLayer.managers.dedicated_host
+   :members:
+   :inherited-members:

docs/api/managers/file.rst

@@ -0,0 +1,5 @@
+.. _file:
+
+.. automodule:: SoftLayer.managers.file
+   :members:
+   :inherited-members:

docs/api/managers/ordering.rst

@@ -0,0 +1,5 @@
+.. _ordering:
+
+.. automodule:: SoftLayer.managers.ordering
+   :members:
+   :inherited-members:

docs/cli.rst

@@ -14,6 +14,7 @@ functionality not fully documented here.
 
    cli/ipsec
    cli/vs
+   cli/ordering
 
 
 .. _config_setup: