Extend some docstrings with useful information

This patch extends some of the docstrings in the `Client` class with
more useful information. The patch also adds `intersphinx` to allow for
linking to other docs within zaqarclient. For example:

    :rtype: :class:`zaqarclient.transport.base.Transport`

will link to the documentation for Transport if it has been generated.

Change-Id: I928d63d74739e9e18709979e79c95b5606d97032

doc/source/conf.py

@@ -32,6 +32,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.coverage',
               'sphinx.ext.pngmath',
               'sphinx.ext.ifconfig',
+              'sphinx.ext.intersphinx',
               'sphinx.ext.graphviz',
               'oslosphinx',
               ]

zaqarclient/queues/v1/client.py

@@ -61,7 +61,7 @@ class Client(object):
 
         :param request: The request to use to load the
             transport instance.
-        :type request: `transport.request.Request`
+        :type request: :class:`zaqarclient.transport.request.Request`
         """
 
         trans = transport.get_transport_for(request,
@@ -80,7 +80,10 @@ class Client(object):
         return req, trans
 
     def transport(self):
-        """Gets a transport based the api url and version."""
+        """Gets a transport based the api url and version.
+
+        :rtype: :class:`zaqarclient.transport.base.Transport`
+        """
         return transport.get_transport_for(self.api_url,
                                            self.api_version)
 
@@ -113,6 +116,10 @@ class Client(object):
     def follow(self, ref):
         """Follows ref.
 
+        This method instanciates a new request instance and requests
+        `ref`. It is intended to be used to follow a reference href
+        gotten from `links` sections in responses like queues' lists.
+
         :params ref: The reference path.
         :type ref: `six.text_type`
         """