Improves doc blocks for all managers with links to product information (softlayer#756)

sudorandom · web-flow · commit dbc637116d2b · 2016-08-22T21:09:11.000-05:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,9 +3,9 @@
 We are happy to accept contributions to softlayer-python.  Please follow the
 guidelines below.  
 
-* Sign our contributor agreement (CLA) You can find the [CLA here](./docs/cla-individual.md).
+* Sign our contributor agreement (CLA) You can find the [CLA here](./docs/dev/cla-individual.md).
 
-* If you're contributing on behalf of your employer we'll need a signed copy of our corporate contributor agreement (CCLA) as well.  You can find the [CCLA here](./docs/cla-corporate.md).
+* If you're contributing on behalf of your employer we'll need a signed copy of our corporate contributor agreement (CCLA) as well.  You can find the [CCLA here](./docs/dev/cla-corporate.md).
     
 * Fork the repo, make your changes, and open a pull request.
 
diff --git a/SoftLayer/managers/block.py b/SoftLayer/managers/block.py
@@ -11,7 +11,12 @@
 
 
 class BlockStorageManager(utils.IdentifierMixin, object):
-    """Manages Block Storage volumes."""
+    """Manages SoftLayer Block Storage volumes.
+
+    See product information here: http://www.softlayer.com/block-storage
+
+    :param SoftLayer.API.BaseClient client: the client instance
+    """
 
     def __init__(self, client):
         self.configuration = {}
diff --git a/SoftLayer/managers/cdn.py b/SoftLayer/managers/cdn.py
@@ -15,7 +15,13 @@
 
 
 class CDNManager(utils.IdentifierMixin, object):
-    """Manage CDN accounts."""
+    """Manage CDN accounts and content.
+
+    See product information here:
+    http://www.softlayer.com/content-delivery-network
+
+    :param SoftLayer.API.BaseClient client: the client instance
+    """
 
     def __init__(self, client):
         self.client = client
diff --git a/SoftLayer/managers/dns.py b/SoftLayer/managers/dns.py
@@ -11,9 +11,11 @@
 
 
 class DNSManager(utils.IdentifierMixin, object):
-    """Domain Name System manager.
+    """Manage SoftLayer DNS.
 
-    :param SoftLayer.API.Client client: the client instance
+    See product information here: http://www.softlayer.com/DOMAIN-SERVICES
+
+    :param SoftLayer.API.BaseClient client: the client instance
 
     """
 
diff --git a/SoftLayer/managers/firewall.py b/SoftLayer/managers/firewall.py
@@ -29,9 +29,11 @@ def has_firewall(vlan):
 
 
 class FirewallManager(utils.IdentifierMixin, object):
-    """Manages firewalls.
+    """Manages SoftLayer firewalls
 
-    :param SoftLayer.API.Client client: the API client instance
+    See product information here: http://www.softlayer.com/firewalls
+
+    :param SoftLayer.API.BaseClient client: the client instance
 
     """
 
diff --git a/SoftLayer/managers/hardware.py b/SoftLayer/managers/hardware.py
@@ -19,7 +19,7 @@
 
 
 class HardwareManager(utils.IdentifierMixin, object):
-    """Manage hardware devices.
+    """Manage SoftLayer hardware servers.
 
     Example::
 
@@ -32,7 +32,9 @@ class HardwareManager(utils.IdentifierMixin, object):
        client = SoftLayer.Client()
        mgr = SoftLayer.HardwareManager(client)
 
-    :param SoftLayer.API.Client client: an API client instance
+    See product information here: http://www.softlayer.com/bare-metal-servers
+
+    :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
diff --git a/SoftLayer/managers/image.py b/SoftLayer/managers/image.py
@@ -13,9 +13,12 @@
 
 
 class ImageManager(utils.IdentifierMixin, object):
-    """Manages server images.
+    """Manages SoftLayer server images.
 
-    :param SoftLayer.API.Client client: an API client instance
+    See product information here:
+    https://knowledgelayer.softlayer.com/topic/image-templates
+
+    :param SoftLayer.API.BaseClient client: the client instance
     """
 
     def __init__(self, client):
diff --git a/SoftLayer/managers/iscsi.py b/SoftLayer/managers/iscsi.py
@@ -10,7 +10,14 @@
 
 
 class ISCSIManager(utils.IdentifierMixin, object):
-    """Manages iSCSI storages."""
+    """Manages SoftLayer iSCSI storage accounts.
+
+    See product information here:
+    https://knowledgelayer.softlayer.com/topic/iscsi
+
+    :param SoftLayer.API.BaseClient client: the client instance
+
+    """
 
     def __init__(self, client):
         self.configuration = {}
diff --git a/SoftLayer/managers/load_balancer.py b/SoftLayer/managers/load_balancer.py
@@ -9,9 +9,12 @@
 
 
 class LoadBalancerManager(utils.IdentifierMixin, object):
-    """Manages load balancers.
+    """Manages SoftLayer load balancers.
+
+    See product information here: http://www.softlayer.com/load-balancing
+
+    :param SoftLayer.API.BaseClient client: the client instance
 
-    :param SoftLayer.API.Client client: the API client instance
     """
 
     def __init__(self, client):
diff --git a/SoftLayer/managers/messaging.py b/SoftLayer/managers/messaging.py
@@ -23,7 +23,7 @@
 
 
 class QueueAuth(requests.auth.AuthBase):
-    """Message Queue authentication for requests.
+    """SoftLayer Message Queue authentication for requests.
 
     :param endpoint: endpoint URL
     :param username: SoftLayer username
@@ -72,7 +72,13 @@ def __call__(self, resp):
 
 
 class MessagingManager(object):
-    """Manage SoftLayer Message Queue."""
+    """Manage SoftLayer Message Queue accounts.
+
+    See product information here: http://www.softlayer.com/message-queue
+
+    :param SoftLayer.API.BaseClient client: the client instance
+
+    """
     def __init__(self, client):
         self.client = client
 
diff --git a/SoftLayer/managers/metadata.py b/SoftLayer/managers/metadata.py
@@ -35,7 +35,10 @@
 
 
 class MetadataManager(object):
-    """Provides an interface for the metadata service.
+    """Provides an interface for the SoftLayer metadata service.
+
+    See product information here:
+    http://sldn.softlayer.com/reference/services/SoftLayer_Resource_Metadata
 
     This provides metadata about the resourse it is called from.
     See `METADATA_ATTRIBUTES` for full list of attributes.
@@ -51,6 +54,8 @@ class MetadataManager(object):
             >>> meta.get('fqdn')
             'test.example.com'
 
+    :param SoftLayer.API.BaseClient client: the client instance
+
     """
 
     attribs = METADATA_MAPPING
diff --git a/SoftLayer/managers/network.py b/SoftLayer/managers/network.py
@@ -36,7 +36,13 @@
 
 
 class NetworkManager(object):
-    """Manage Networks."""
+    """Manage SoftLayer network objects: VLANs, subnets, IPs and rwhois
+
+    See product information here: http://www.softlayer.com/networking
+
+    :param SoftLayer.API.BaseClient client: the client instance
+
+    """
     def __init__(self, client):
         self.client = client
         self.account = client['Account']
diff --git a/SoftLayer/managers/object_storage.py b/SoftLayer/managers/object_storage.py
@@ -16,7 +16,13 @@
 
 
 class ObjectStorageManager(object):
-    """Manager for Object Storage."""
+    """Manager for SoftLayer Object Storage accounts.
+
+    See product information here: http://www.softlayer.com/object-storage
+
+    :param SoftLayer.API.BaseClient client: the client instance
+
+    """
 
     def __init__(self, client):
         self.client = client
diff --git a/SoftLayer/managers/ordering.py b/SoftLayer/managers/ordering.py
@@ -8,9 +8,9 @@
 
 
 class OrderingManager(object):
-    """Manages hardware devices.
+    """Manager to help ordering via the SoftLayer API.
 
-    :param SoftLayer.API.Client client: an API client instance
+    :param SoftLayer.API.BaseClient client: the client instance
     """
 
     def __init__(self, client):
diff --git a/SoftLayer/managers/sshkey.py b/SoftLayer/managers/sshkey.py
@@ -10,9 +10,12 @@
 
 
 class SshKeyManager(utils.IdentifierMixin, object):
-    """Manages account SSH keys.
+    """Manages account SSH keys in SoftLayer.
 
-    :param SoftLayer.API.Client client: an API client instance
+    See product information here:
+    https://knowledgelayer.softlayer.com/procedure/ssh-keys
+
+    :param SoftLayer.API.BaseClient client: the client instance
     """
 
     def __init__(self, client):
diff --git a/SoftLayer/managers/ssl.py b/SoftLayer/managers/ssl.py
@@ -8,9 +8,9 @@
 
 
 class SSLManager(object):
-    """Manages SSL certificates.
+    """Manages SSL certificates in SoftLayer.
 
-    :param SoftLayer.API.Client client: an API client instance
+    See product information here: http://www.softlayer.com/ssl-certificates
 
     Example::
 
@@ -23,6 +23,8 @@ class SSLManager(object):
        client = SoftLayer.Client()
        mgr = SoftLayer.SSLManager(client)
 
+    :param SoftLayer.API.BaseClient client: the client instance
+
     """
 
     def __init__(self, client):
diff --git a/SoftLayer/managers/ticket.py b/SoftLayer/managers/ticket.py
@@ -10,9 +10,12 @@
 
 
 class TicketManager(utils.IdentifierMixin, object):
-    """Manages support Tickets.
+    """Manages SoftLayer support tickets.
+
+    See product information here: http://www.softlayer.com/support
+
+    :param SoftLayer.API.BaseClient client: the client instance
 
-    :param SoftLayer.API.Client client: an API client instance
     """
 
     def __init__(self, client):
@@ -46,8 +49,7 @@ def get_ticket(self, ticket_id):
         """Get details about a ticket.
 
         :param integer ticket_id: the ticket ID
-        :returns: A dictionary containing a large amount of information about
-                  the specified ticket.
+        :returns: dict -- information about the specified ticket
 
         """
         mask = ('id, title, assignedUser[firstName, lastName],status,'
@@ -91,7 +93,8 @@ def upload_attachment(self, ticket_id=None, file_path=None,
         :param string file_name:
                                   The name of the attachment shown
                                   in the ticket
-        :returns The uploaded attachment
+
+        :returns: dict -- The uploaded attachment
         """
         file_content = None
         with open(file_path, 'rb') as attached_file:
@@ -109,7 +112,8 @@ def attach_hardware(self, ticket_id=None, hardware_id=None):
 
         :param integer ticket_id: the id of the ticket to attach to
         :param integer hardware_id: the id of the hardware to attach
-        :returns The new ticket attachment
+
+        :returns: dict -- The new ticket attachment
         """
         return self.ticket.addAttachedHardware(hardware_id, id=ticket_id)
 
@@ -118,7 +122,8 @@ def attach_virtual_server(self, ticket_id=None, virtual_id=None):
 
         :param integer ticket_id: the id of the ticket to attach to
         :param integer virtual_id: the id of the virtual server to attach
-        :returns The new ticket attachment
+
+        :returns: dict -- The new ticket attachment
         """
         return self.ticket.addAttachedVirtualGuest(virtual_id, id=ticket_id)
 
@@ -127,7 +132,8 @@ def detach_hardware(self, ticket_id=None, hardware_id=None):
 
         :param ticket_id: the id of the ticket to detach from
         :param hardware_id: the id of the hardware to detach
-        :return: Whether the detachment was successful
+
+        :returns: bool -- Whether the detachment was successful
         """
         return self.ticket.removeAttachedHardware(hardware_id, id=ticket_id)
 
@@ -136,6 +142,7 @@ def detach_virtual_server(self, ticket_id=None, virtual_id=None):
 
         :param ticket_id: the id of the ticket to detach from
         :param virtual_id: the id of the virtual server to detach
-        :return: Whether the detachment was successful
+
+        :returns: bool -- Whether the detachment was successful
         """
         return self.ticket.removeAttachedVirtualGuest(virtual_id, id=ticket_id)
diff --git a/SoftLayer/managers/vs.py b/SoftLayer/managers/vs.py
@@ -17,13 +17,9 @@
 
 
 class VSManager(utils.IdentifierMixin, object):
-    """Manages Virtual Servers.
+    """Manages SoftLayer Virtual Servers.
 
-    :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.
+    See product information here: http://www.softlayer.com/virtual-servers
 
     Example::
 
@@ -36,6 +32,13 @@ class VSManager(utils.IdentifierMixin, object):
            client = SoftLayer.Client()
            mgr = SoftLayer.VSManager(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.
+
     """
 
     def __init__(self, client, ordering_manager=None):
diff --git a/docs/dev/cla-corporate.md b/docs/dev/cla-corporate.md
diff --git a/docs/dev/cla-individual.md b/docs/dev/cla-individual.md
diff --git a/docs/dev/index.rst b/docs/dev/index.rst
