Merge "Update 'make_client' kazoo docs and link to them"

1 files changed, 37 insertions, 1 deletions

diff --git a/taskflow/utils/kazoo_utils.py b/taskflow/utils/kazoo_utils.py
index f681dc4..c60a9a8 100644
--- a/taskflow/utils/kazoo_utils.py
+++ b/taskflow/utils/kazoo_utils.py
@@ -151,7 +151,43 @@ def check_compatible(client, min_version=None, max_version=None):
 
 
 def make_client(conf):
-    """Creates a kazoo client given a configuration dictionary."""
+    """Creates a `kazoo`_ `client`_ given a configuration dictionary.
+
+    :param conf: configuration dictionary that will be used to configure
+                 the created client
+    :type conf: dict
+
+    The keys that will be extracted are:
+
+    - ``read_only``: boolean that specifies whether to allow connections to
+      read only servers, defaults to ``False``
+    - ``randomize_hosts``: boolean that specifies whether to randomize
+      host lists provided, defaults to ``False``
+    - ``command_retry``: a kazoo `retry`_ object (or dict of options which
+      will be used for creating one) that will be used for retrying commands
+      that are executed
+    - ``connection_retry``: a kazoo `retry`_ object (or dict of options which
+      will be used for creating one)  that will be used for retrying
+      connection failures that occur
+    - ``hosts``: a string, list, set (or dict with host keys) that will
+      specify the hosts the kazoo client should be connected to, if none
+      is provided then ``localhost:2181`` will be used by default
+    - ``timeout``: a float value that specifies the default timeout that the
+      kazoo client will use
+    - ``handler``: a kazoo handler object that can be used to provide the
+      client with alternate async strategies (the default is `thread`_
+      based, but `gevent`_, or `eventlet`_ ones can be provided as needed)
+
+    .. _client: http://kazoo.readthedocs.org/en/latest/api/client.html
+    .. _kazoo: kazoo.readthedocs.org/
+    .. _retry: http://kazoo.readthedocs.org/en/latest/api/retry.html
+    .. _gevent: http://kazoo.readthedocs.org/en/latest/api/\
+                handlers/gevent.html
+    .. _eventlet: http://kazoo.readthedocs.org/en/latest/api/\
+                  handlers/eventlet.html
+    .. _thread: http://kazoo.readthedocs.org/en/latest/api/\
+                handlers/threading.html
+    """
     # See: http://kazoo.readthedocs.org/en/latest/api/client.html
     client_kwargs = {
         'read_only': bool(conf.get('read_only')),