Fix all warnings when building the docs

cloudbridge/cloud/interfaces/resources.py

@@ -31,7 +31,7 @@ class CloudResource(object):
 
     This interface has a  _provider property that can be used to access the
     provider associated with the resource, which is only intended for use by
-    subclasses. Every cloudbridge resource also has an id, a name and a
+    subclasses. Every CloudBridge resource also has an id, a name and a
     label property. The id property is a unique identifier for the resource.
     The name is a more user-friendly version of an id, suitable for
     display to an end-user. However, it cannot be used in place of id. See
@@ -58,11 +58,11 @@ class CloudResource(object):
         Get the resource identifier.
 
         The id property is used to uniquely identify the resource, and is an
-        opaque value which should not be interpreted by cloudbridge clients,
+        opaque value which should not be interpreted by CloudBridge clients,
         and is a value meaningful to the underlying cloud provider.
 
-        :rtype: ``str`` :return: ID for this resource as returned by the cloud
-        middleware.
+        :rtype: ``str``
+        :return: ID for this resource as returned by the cloud middleware.
         """
         pass
 
@@ -72,30 +72,32 @@ class CloudResource(object):
         Get the name id for the resource.
 
         The name property is typically a user-friendly id value for the
-        resource. The name is different from the id property in the
-        following ways:
-        1. The name property is often a more user-friendly value to
-           display to the user than the id property.
-        2. The name may sometimes be the same as the id, but should never
-           be used in place of the id.
-        3. The id is what will uniquely identify a resource, and will be used
-           internally by cloudbridge for all get operations etc.
-        4. All resources have a name.
-        5. The name is read-only.
-        6. However, the name may not necessarily be unique, which is the
-           reason why it should not be used for uniquely identifying a
-           resource.
+        resource. The name is different from the id property in the following
+        ways:
+
+         1. The name property is often a more user-friendly value to
+            display to the user than the id property.
+         2. The name may sometimes be the same as the id, but should never
+            be used in place of the id.
+         3. The id is what will uniquely identify a resource, and will be used
+            internally by CloudBridge for all get operations etc.
+         4. All resources have a name.
+         5. The name is read-only.
+         6. However, the name may not necessarily be unique, which is the
+            reason why it should not be used for uniquely identifying a
+            resource.
+
         Example:
-        The AWS machine image name maps to a cloudbridge name. It is not
-        editable and is a user friendly name such as 'Ubuntu 14.04' and
+        The AWS machine image name maps to a CloudBridge name. It is not
+        editable and is a user friendly name such as 'Ubuntu 18.04' and
         corresponds to the ami-name. It is distinct from the ami-id, which
-        maps to cloudbridge's id property. The ami-name cannot be edited, and
+        maps to CloudBridge's id property. The ami-name cannot be edited, and
         is set at creation time. It is not necessarily unique.
-        In Azure, the machine image's name corresponds to cloudbridge's name
+        In Azure, the machine image's name corresponds to CloudBridge's name
         property. In Azure, it also happens to be the same as the id property.
 
         The name property and the label property share the same character
-        restrictions. see :py:attr:`~LabeledCloudResource.label`
+        restrictions. See :py:attr:`~LabeledCloudResource.label`.
         """
         pass
 
@@ -119,6 +121,7 @@ class LabeledCloudResource(CloudResource):
         in the underlying cloud provider, or be simulated through tags/labels.
 
         The label property adheres to the following restrictions:
+
         * Must be at least 3 characters in length.
         * Cannot be longer than 63 characters.
         * May only contain ASCII characters comprising of lowercase letters,
@@ -127,18 +130,19 @@ class LabeledCloudResource(CloudResource):
           (i.e. cannot begin or end with a dash)
 
         Some resources may not support labels, in which case, a
-        NotImplementedError will be thrown.
+        ``NotImplementedError`` will be thrown.
 
         :rtype: ``str``
         :return: Label for this resource as returned by the cloud middleware.
-        :throws NotImplementedError if this resource does not support labels
+        :raise: ``NotImplementedError`` if this resource does not support
+                labels.
         """
         pass
 
 
 class Configuration(dict):
     """
-    Represents a cloudbridge configuration object
+    Represents a CloudBridge configuration object
     """
 
     @abstractproperty
@@ -505,6 +509,9 @@ class Instance(ObjectLifeCycleMixin, LabeledCloudResource):
     def label(self, value):
         """
         Set the instance label.
+
+        :type value: ``str``
+        :param value: The value to set the label to.
         """
         pass
 
@@ -893,6 +900,9 @@ class Network(ObjectLifeCycleMixin, LabeledCloudResource):
     def label(self, value):
         """
         Set the resource label.
+
+        :type value: ``str``
+        :param value: The value to set the label to.
         """
         pass
 
@@ -1011,6 +1021,9 @@ class Subnet(ObjectLifeCycleMixin, LabeledCloudResource):
     def label(self, value):
         """
         Set the resource label.
+
+        :type value: ``str``
+        :param value: The value to set the label to.
         """
         pass
 
@@ -1230,6 +1243,9 @@ class Router(LabeledCloudResource):
     def label(self, value):
         """
         Set the resource label.
+
+        :type value: ``str``
+        :param value: The value to set the label to.
         """
         pass
 

cloudbridge/cloud/interfaces/services.py

@@ -699,7 +699,7 @@ class SubnetService(PageableObjectMixin, CloudService):
         :param subnet_id: The ID of the subnet to retrieve.
 
         :rtype: ``object`` of :class:`.Subnet`
-        return: a Subnet object
+        :return: a Subnet object
         """
         pass
 

docs/api_docs/cloud/services.rst

@@ -55,7 +55,7 @@ SubnetService
 
 FloatingIPService
 -----------------
-.. autoclass:: cloudbridge.cloud.interfaces.services.FloatingIPService
+.. autoclass:: cloudbridge.cloud.interfaces.resources.FloatingIPContainer
     :members:
 
 RouterService
@@ -65,7 +65,7 @@ RouterService
 
 GatewayService
 -----------------
-.. autoclass:: cloudbridge.cloud.interfaces.services.GatewayService
+.. autoclass:: cloudbridge.cloud.interfaces.resources.GatewayContainer
     :members:
 
 BucketService

docs/conf.py

@@ -121,7 +121,9 @@ html_theme = 'sphinx_rtd_theme'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'style_external_links': True
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -146,7 +148,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/getting_started.rst

@@ -214,7 +214,7 @@ listed in order to help map each resource with the service that handles it.
 Note that labeled resources allow to find by label, while unlabeled
 resources find by name or their special properties (eg: public_ip for
 floating IPs). For more detailed information on the types of resources and
-their provider mappings, see :doc:`topics/resource_types_and_mappings`.
+their provider mappings, see :doc:`topics/resource_types_and_mapping`.
 
 .. code-block:: python
 

docs/topics/aws_mapping.rst

@@ -1,3 +1,6 @@
+Detailed AWS Type and Resource Mappings
+=======================================
+
 AWS Dashboard
 -------------
 AWS has a particular dashboard as resources are found within different
@@ -88,7 +91,7 @@ web portal.
    resources in AWS. By default, this label will appear in the first
    column.
 
-.. figure:: captures/az-ami-dash.png
+.. figure:: captures/aws-ami-dash.png
    :alt: name, ID, and label properties for AWS EC2 AMIs
 
    When an AWS resource allows for an unchangeable name, the CloudBridge

docs/topics/azure_mapping.rst

@@ -1,3 +1,6 @@
+Detailed Azure Type and Resource Mappings
+=========================================
+
 Azure - Labeled Resources
 -------------------------
 +---------------------------------------+------------------------+-------+------------------------+------------------------------------+
@@ -106,8 +109,9 @@ It is also important to note that some of these resources are paid and
 required a plan to use, while others are free but likewise require accepting
 certain terms before being used. These plans and terms are passed and
 accepted silently by CloudBridge in order to keep the code cloud-independent.
-We therefore encourage using the `marketplace website<https://azuremarketplace.microsoft.com/en-us>`_
-to view image and plan details before using them in CloudBridge.
+We therefore encourage using the
+`marketplace website <https://azuremarketplace.microsoft.com/en-us>`_
+to view the images and plan details before using them in CloudBridge.
 
 Additionally, Subnets are a particular resource in Azure because they are
 not simply found in the Resource Group like most resources, but are rather
@@ -214,4 +218,4 @@ Finally, Firewall Rules in Azure differ from traditional unlabeled
 resources by the fact that they do not take a `name` parameter at creation.
 These rules can be found within each Firewall (i.e. Security Group) in the
 Azure web portal, and will have an automatically generated `name` of the form
-'cb-rule-[int]'.
+'cb-rule-[int]'.

docs/topics/object_storage.rst

@@ -1,5 +1,5 @@
 Working with object storage
-==========================
+===========================
 Object storage provides a simple way to store and retrieve large amounts of
 unstructured data over HTTP. Object Storage is also referred to as Blob (Binary
 Large OBject) Storage by Azure, and Simple Storage Service (S3) by Amazon.

docs/topics/os_mapping.rst

@@ -1,5 +1,8 @@
+Detailed OpenStack Type and Resource Mappings
+=============================================
+
 OpenStack - Labeled Resources
------------------------
+-----------------------------
 +------------------------+------------------------+-----------+----------------+----------+
 | Labeled Resource       | OS Resource Type       | CB ID     | CB Name        | CB Label |
 +========================+========================+===========+================+==========+
@@ -22,32 +25,32 @@ OpenStack - Labeled Resources
 
 The resources listed above are labeled, they thus have both the `name` and
 `label` properties in CloudBridge. These resources require a mandatory `label`
-parameter at creation. For all labeled resources, the `label` property in OpenStack
-maps to the Name attribute. However, unlike in Azure or AWS, no resource has
-an unchangeable name by which to identify it in our OpenStack implementation.
-The `name` property will therefore map to the ID, preserving its role as an unchangeable 
-identifier even though not easily readable in this context. Finally, labeled resources
-support a `label` parameter for the `find` method in their corresponding services.
-The below screenshots will help map these properties to OpenStack objects in the
-web portal.
-Additionally, although OpenStack Security Groups are not associated with a
-specific network, such an association is done in CloudBridge, due to its
-necessity in AWS. As such, the VMFirewall creation method requires a
-`network` parameter and the association is accomplished in OpenStack through
-the description, by appending the following string to the user-provided description
-(if any) at creation: "[CB-AUTO-associated-network-id: associated_net_id]"
+parameter at creation. For all labeled resources, the `label` property in
+OpenStack maps to the Name attribute. However, unlike in Azure or AWS, no
+resource has an unchangeable name by which to identify it in our OpenStack
+implementation. The `name` property will therefore map to the ID, preserving
+its role as an unchangeable identifier even though not easily readable in this
+context. Finally, labeled resources support a `label` parameter for the `find`
+method in their corresponding services. The below screenshots will help map
+these properties to OpenStack objects in the web portal. Additionally, although
+OpenStack Security Groups are not associated with a specific network, such an
+association is done in CloudBridge, due to its necessity in AWS. As such, the
+VMFirewall creation method requires a `network` parameter and the association
+is accomplished in OpenStack through the description, by appending the
+following string to the user-provided description (if any) at creation:
+"[CB-AUTO-associated-network-id: associated_net_id]"
 
 .. figure:: captures/os-instance-dash.png
    :alt: name, ID, and label properties for OS Instances
 
    The CloudBridge `name` and `ID` properties map to the unchangeable
    resource ID in OpenStack as resources do not allow for an unchangeable
-   name. The `label` property maps to the 'Name' for all resources in 
+   name. The `label` property maps to the 'Name' for all resources in
    OpenStack. By default, this label will appear in the first column.
 
 
 OpenStack - Unlabeled Resources
----------------------------
+-------------------------------
 +-----------------------+------------------------+-------+---------+----------+
 | Unlabeled Resource    | OS Resource Type       | CB ID | CB Name | CB Label |
 +=======================+========================+=======+=========+==========+
@@ -76,7 +79,7 @@ services.
 
 
 OpenStack - Special Unlabeled Resources
------------------------------------
+---------------------------------------
 +--------------------------+------------------------+-------+------------------------------------------------------------------------+----------+
 | Unlabeled Resource       | OS Resource Type       | CB ID | CB Name                                                                | CB Label |
 +==========================+========================+=======+========================================================================+==========+
@@ -105,4 +108,4 @@ Finally, Firewall Rules in OpenStack differ from traditional unlabeled resources
 by the fact that they do not take a `name` parameter at creation, and the
 `name` property is automatically generated from the rule's properties, as
 shown above. These rules can be found within each Firewall (i.e. Security
-Group) in the web portal, and will not have any name in the OpenStack dashboard.
+Group) in the web portal, and will not have any name in the OpenStack dashboard.

docs/topics/overview.rst

@@ -14,4 +14,5 @@ Introductions to all the key parts of CloudBridge you'll need to know:
     Paging and iteration <paging_and_iteration.rst>
     Using block storage <block_storage.rst>
     Using object storage <object_storage.rst>
+    Resource types and mapping <resource_types_and_mapping.rst>
     Troubleshooting <troubleshooting.rst>

docs/topics/provider_development.rst

@@ -56,8 +56,8 @@ You should see the tests fail with the following message:
 
 .. code-block:: bash
 
-    TypeError: Can't instantiate abstract class GCECloudProvider with abstract
-    methods storage, compute, security, network
+    "TypeError: Can't instantiate abstract class GCECloudProvider with abstract
+    methods storage, compute, security, network."
 
 6. Therefore, our next step is to implement these methods. We can start off by
 implementing these methods in ``provider.py`` and raising a
@@ -125,8 +125,8 @@ tests to fail:
 
 .. code-block:: bash
 
-    TypeError: Can't instantiate abstract class GCESecurityService with abstract
-    methods key_pairs, security_groups
+    "TypeError: Can't instantiate abstract class GCESecurityService with abstract
+    methods key_pairs, security_groups."
 
 The Abstract Base Classes are doing their job and flagging all methods that
 need to be implemented.
@@ -180,8 +180,8 @@ Once again, running the tests will complain of missing methods:
 
 .. code-block:: bash
 
-    TypeError: Can't instantiate abstract class GCEKeyPairService with abstract
-    methods create, find, get, list
+    "TypeError: Can't instantiate abstract class GCEKeyPairService with abstract
+    methods create, find, get, list."
 
 11. Keep implementing the methods till the security service works, and the
 tests pass.

docs/topics/resource_types_and_mapping.rst

@@ -10,30 +10,33 @@ providers' resources and features. Notably, in order to create a robust and
 conceptually consistent cross-cloud library, resources were separated into
 `labeled` and `unlabeled resources,` and were given three main properties:
 `ID`, `name`, and `label`.
+
 The `ID` corresponds to a unique identifier that can be reliably used to
 reference a resource. Users can safely use an ID knowing that it will always
 point to the same resource. All resources have an `ID` property, thus making
-it the recommended oproperty for reliably identifying a resource.
+it the recommended property for reliably identifying a resource.
+
 The `label` property, conversely, is a modifiable value that does not need
-to be unique. Unlike the name property, it is not used to identify a
+to be unique. Unlike the `name` property, it is not used to identify a
 particular resource, but rather label a resource for easier distinction.
-Only labeled resources have the label property, and these resources require
+Only labeled resources have the `label` property, and these resources require
 a `label` parameter be set at creation time.
-The `name` property corresponds to an unchangeable and unique designation for
-a particular resource. This property is meant to be, in some ways, a more
+
+The `name` property corresponds to an unchangeable and unique designation for a
+particular resource. This property is meant to be, in some ways, a more
 human-readable identifier. Thus, when no conceptually comparable property
-exists for a given resource in a particular provider, the ID is returned
-instead, as is the case for all OpenStack and some AWS resources. Given the 
-discrepancy between providers, using the `name` property is not advisable 
-for cross-cloud usage of the library. Labeled resources will use the label
-given at creation as a prefix to the set name, when this property is separable
-from the ID as is the case in Azure and some AWS resources. Finally, unlabeled
-resources will always support a `name`, and some unlabeled resources will require
-a name parameter at creation. Below is a list of all resources classified by
-whether they support a `label` property.
+exists for a given resource in a particular provider, the `ID` is returned
+instead, as is the case for all OpenStack and some AWS resources. Given the
+discrepancy between providers, using the `name` property is not advisable for
+cross-cloud usage of the library. Labeled resources will use the label given at
+creation as a prefix to the set `name`, when this property is separable from
+the `ID` as is the case in Azure and some AWS resources. Finally, unlabeled
+resources will always support a `name`, and some unlabeled resources will
+require a `name` parameter at creation. Below is a list of all resources
+classified by whether they support a `label` property.
 
 +-------------------+---------------------+
-| Labeled Resources | Unlabeled Resources | 
+| Labeled Resources | Unlabeled Resources |
 +===================+=====================+
 | Instance          | Key Pair            |
 +-------------------+---------------------+
@@ -60,6 +63,14 @@ properties to provider objects, as well as some useful dashboard navigation.
 These sections will thus present summary tables delineating the different types of
 CloudBridge resources, as well as present some design decisions made to
 preserve consistency across providers:
--`Detailed Azure Mappings <azure_mapping.html>`_
--`Detailed AWS Mappings <aws_mapping.html>`_
--`Detailed OpenStack Mappings <os_mapping.html>`_
+
+.. toctree::
+   :maxdepth: 1
+
+   Detailed AWS Mappings <aws_mapping.rst>
+   Detailed Azure Mappings <azure_mapping.rst>
+   Detailed OpenStack Mappings <os_mapping.rst>
+
+.. - `Detailed Azure Mappings <azure_mapping.html>`_
+.. - `Detailed AWS Mappings <aws_mapping.html>`_
+.. - `Detailed OpenStack Mappings <os_mapping.html>`_