Implement message docs

This change organizes the message docs by topic rather than letting
autodoc organize methods by the order they appear in the _proxy.py file.

These were not previously included so they're technically all brand new.
There are some minor adjustments made to the docstrings as they weren't
known to be raising warnings before due to not actually being included
anywhere.

Change-Id: Id4b8f08015a6f00b8134fcd2a01506562d9787fb

doc/source/users/guides/message.rst

@@ -0,0 +1,8 @@
+Using OpenStack Message
+=======================
+
+Before working with the Message service, you'll need to create a connection
+to your OpenStack cloud by following the :doc:`connect` user guide. This will
+provide you with the ``conn`` variable used in the examples below.
+
+.. TODO(briancurtin): Implement this guide

doc/source/users/index.rst

@@ -36,6 +36,7 @@ approach, this is where you'll want to begin.
    Identity <guides/identity>
    Image <guides/image>
    Key Manager <guides/key_manager>
+   Message <guides/message>
    Network <guides/network>
    Object Store <guides/object_store>
    Orchestration <guides/orchestration>
@@ -79,6 +80,8 @@ but listed below are the ones provided by this SDK by default.
    Image v1 <proxies/image_v1>
    Image v2 <proxies/image_v2>
    Key Manager <proxies/key_manager>
+   Message v1 <proxies/message_v1>
+   Message v2 <proxies/message_v2>
    Network <proxies/network>
    Object Store <proxies/object_store>
    Orchestration <proxies/orchestration>

doc/source/users/proxies/message_v1.rst

@@ -0,0 +1,30 @@
+Message API v1
+==============
+
+For details on how to use message, see :doc:`/users/guides/message`
+
+.. automodule:: openstack.message.v1._proxy
+
+The Message v1 Class
+--------------------
+
+The message high-level interface is available through the ``message`` member
+of a :class:`~openstack.connection.Connection` object.  The ``message``
+member will only be added if the service is detected.
+
+Message Operations
+^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.message.v1._proxy.Proxy
+
+   .. automethod:: openstack.message.v1._proxy.Proxy.claim_messages
+   .. automethod:: openstack.message.v1._proxy.Proxy.create_messages
+   .. automethod:: openstack.message.v1._proxy.Proxy.delete_message
+
+Queue Operations
+^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.message.v1._proxy.Proxy
+
+   .. automethod:: openstack.message.v1._proxy.Proxy.create_queue
+   .. automethod:: openstack.message.v1._proxy.Proxy.delete_queue

doc/source/users/proxies/message_v2.rst

@@ -0,0 +1,53 @@
+Message API v2
+==============
+
+For details on how to use message, see :doc:`/users/guides/message`
+
+.. automodule:: openstack.message.v2._proxy
+
+The Message v2 Class
+--------------------
+
+The message high-level interface is available through the ``message`` member
+of a :class:`~openstack.connection.Connection` object.  The ``message``
+member will only be added if the service is detected.
+
+Message Operations
+^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.message.v2._proxy.Proxy
+
+   .. automethod:: openstack.message.v2._proxy.Proxy.post_message
+   .. automethod:: openstack.message.v2._proxy.Proxy.delete_message
+   .. automethod:: openstack.message.v2._proxy.Proxy.get_message
+   .. automethod:: openstack.message.v2._proxy.Proxy.messages
+
+Queue Operations
+^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.message.v2._proxy.Proxy
+
+   .. automethod:: openstack.message.v2._proxy.Proxy.create_queue
+   .. automethod:: openstack.message.v2._proxy.Proxy.delete_queue
+   .. automethod:: openstack.message.v2._proxy.Proxy.get_queue
+   .. automethod:: openstack.message.v2._proxy.Proxy.queues
+
+Claim Operations
+^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.message.v2._proxy.Proxy
+
+   .. automethod:: openstack.message.v2._proxy.Proxy.create_claim
+   .. automethod:: openstack.message.v2._proxy.Proxy.update_claim
+   .. automethod:: openstack.message.v2._proxy.Proxy.delete_claim
+   .. automethod:: openstack.message.v2._proxy.Proxy.get_claim
+
+Subscription Operations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: openstack.message.v2._proxy.Proxy
+
+   .. automethod:: openstack.message.v2._proxy.Proxy.create_subscription
+   .. automethod:: openstack.message.v2._proxy.Proxy.delete_subscription
+   .. automethod:: openstack.message.v2._proxy.Proxy.get_subscription
+   .. automethod:: openstack.message.v2._proxy.Proxy.subscriptions

openstack/message/v1/_proxy.py

@@ -48,12 +48,14 @@ class Proxy(proxy.BaseProxy):
     def create_messages(self, values):
         """Create new messages
 
-        :param list values: The list of
-                    :class:`~openstack.message.v1.message.Message`s to create.
+        :param values: The list of
+                       :class:`~openstack.message.v1.message.Message` objects
+                       to create.
+        :type values: :py:class:`list`
 
-        :returns: The results of message creation
-        :rtype: list messages: The list of
-                    :class:`~openstack.message.v1.message.Message`s created.
+        :returns: The list of
+                  :class:`~openstack.message.v1.message.Message` objects
+                  that were created.
         """
         return message.Message.create_messages(self._session, values)
 
@@ -63,9 +65,9 @@ class Proxy(proxy.BaseProxy):
         :param value: The value must be a
                       :class:`~openstack.message.v1.claim.Claim` instance.
 
-        :returns: The results of a claim
-        :rtype: list messages: The list of
-                    :class:`~openstack.message.v1.message.Message`s claimed.
+        :returns: The list of
+                  :class:`~openstack.message.v1.message.Message` objects
+                  that were claimed.
         """
         return claim.Claim.claim_messages(self._session, value)
 

openstack/message/v2/_proxy.py

@@ -80,7 +80,8 @@ class Proxy(proxy2.BaseProxy):
         """Post messages to given queue
 
         :param queue_name: The name of target queue to post message to.
-        :param list messages: List of messages body and TTL to post.
+        :param messages: List of messages body and TTL to post.
+        :type messages: :py:class:`list`
 
         :returns: A string includes location of messages successfully posted.
         """