Include documentation of the utility modules

Add a documentation section that uses the automodule
sphinx documentation generator to build a utility page
that shows people what the utility modules taskflow
uses for *internal* usage are and include a warning to
try to avoid end-users from using these modules (better
to warn than not warn).

This also adds on docstrings to various functions that
were missing it so that they appear correctly in the
generated documentation.

Change-Id: Ibd5695927601614f31793ea5450887694f4320ae

doc/source/index.rst

@@ -70,13 +70,9 @@ TaskFlow into your project:
   ``[TaskFlow]`` to your emails subject to get an even faster response).
 * Follow (or at least attempt to follow) some of the established
   `best practices`_ (feel free to add your own suggested best practices).
-
-.. warning::
-
-        External usage of internal helpers and other internal utility functions
-        and modules should be kept to a *minimum* as these may be altered,
-        refactored or moved *without* notice. If you are unsure whether to use
-        a function, class, or module, please ask (see above).
+* Keep in touch with the team (see above); we are all friendly and enjoy
+  knowing your use cases and learning how we can help make your lives easier
+  by adding or adjusting functionality in this library.
 
 .. _IRC: irc://chat.freenode.net/openstack-state-management
 .. _best practices: http://wiki.openstack.org/wiki/TaskFlow/Best_practices
@@ -92,6 +88,7 @@ Miscellaneous
    exceptions
    states
    types
+   utils
 
 Indices and tables
 ==================

doc/source/utils.rst

@@ -0,0 +1,49 @@
+---------
+Utilities
+---------
+
+.. warning::
+
+    External usage of internal utility functions and modules should be kept
+    to a **minimum** as they may be altered, refactored or moved to other
+    locations **without** notice (and without the typical deprecation cycle).
+
+Async
+~~~~~
+
+.. automodule:: taskflow.utils.async_utils
+
+Deprecation
+~~~~~~~~~~~
+
+.. automodule:: taskflow.utils.deprecation
+
+Kazoo
+~~~~~
+
+.. automodule:: taskflow.utils.kazoo_utils
+
+Locks
+~~~~~
+
+.. automodule:: taskflow.utils.lock_utils
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+.. automodule:: taskflow.utils.misc
+
+Persistence
+~~~~~~~~~~~
+
+.. automodule:: taskflow.utils.persistence_utils
+
+Reflection
+~~~~~~~~~~
+
+.. automodule:: taskflow.utils.reflection
+
+Threading
+~~~~~~~~~
+
+.. automodule:: taskflow.utils.threading_utils

taskflow/utils/deprecation.py

@@ -14,7 +14,6 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-import functools
 import warnings
 
 import six
@@ -193,8 +192,12 @@ def _moved_decorator(kind, new_attribute_name, message=None,
     return decorator
 
 
-"""Decorates a *instance* property that was moved to another location."""
-moved_property = functools.partial(_moved_decorator, 'Property')
+def moved_property(new_attribute_name, message=None,
+                   version=None, removal_version=None):
+    """Decorates a *instance* property that was moved to another location."""
+
+    return _moved_decorator('Property', new_attribute_name, message=message,
+                            version=version, removal_version=removal_version)
 
 
 def moved_class(new_class, old_class_name, old_module_name, message=None,

taskflow/utils/kazoo_utils.py

@@ -95,8 +95,12 @@ class KazooTransactionException(k_exc.KazooException):
 
 
 def checked_commit(txn):
-    # Until https://github.com/python-zk/kazoo/pull/224 is fixed we have
-    # to workaround the transaction failing silently.
+    """Commits a kazoo transcation and validates the result.
+
+    NOTE(harlowja): Until https://github.com/python-zk/kazoo/pull/224 is fixed
+    or a similar pull request is merged we have to workaround the transaction
+    failing silently.
+    """
     if not txn.operations:
         return []
     results = txn.commit()

taskflow/utils/misc.py

@@ -342,11 +342,27 @@ def capture_failure():
 
     For example::
 
-      except Exception:
-        with capture_failure() as fail:
-            LOG.warn("Activating cleanup")
-            cleanup()
-            save_failure(fail)
+        >>> from taskflow.utils import misc
+        >>>
+        >>> def cleanup():
+        ...     pass
+        ...
+        >>>
+        >>> def save_failure(f):
+        ...     print("Saving %s" % f)
+        ...
+        >>>
+        >>> try:
+        ...     raise IOError("Broken")
+        ... except Exception:
+        ...     with misc.capture_failure() as fail:
+        ...         print("Activating cleanup")
+        ...         cleanup()
+        ...         save_failure(fail)
+        ...
+        Activating cleanup
+        Saving Failure: IOError: Broken
+
     """
     exc_info = sys.exc_info()
     if not any(exc_info):