From 2830304407fb097dda5196a8a99905106865d80f Mon Sep 17 00:00:00 2001
From: David Wilson <dw@botanicus.net>
Date: Thu, 5 Oct 2017 14:10:18 +0530
Subject: [PATCH] docs: move mitogen.utils docs to Sphinx.

---
 docs/api.rst     | 54 ++++++++++++++++++++++++++++++++++++++++++++++--
 mitogen/utils.py | 21 -------------------
 2 files changed, 52 insertions(+), 23 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 63f258bb..558182b3 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -675,8 +675,58 @@ Broker Class
 Utility Functions
 =================
 
-.. automodule:: mitogen.utils
-  :members:
+.. module:: mitogen.utils
+
+A random assortment of utility functions useful on masters and children.
+
+.. currentmodule:: mitogen.utils
+.. function:: disable_site_packages
+
+    Remove all entries mentioning ``site-packages`` or ``Extras`` from the
+    system path. Used primarily for testing on OS X within a virtualenv, where
+    OS X bundles some ancient version of the :py:mod:`six` module.
+
+.. currentmodule:: mitogen.utils
+.. function:: log_to_file (path=None, io=True, level='INFO')
+
+    Install a new :py:class:`logging.Handler` writing applications logs to the
+    filesystem. Useful when debugging slave IO problems.
+
+    :param str path:
+        If not ``None``, a filesystem path to write logs to. Otherwise, logs
+        are written to :py:data:`sys.stderr`.
+
+    :param bool io:
+        If ``True``, include extremely verbose IO logs in the output. Useful
+        for debugging hangs, less useful for debugging application code.
+
+    :param str level:
+        Name of the :py:mod:`logging` package constant that is the minimum
+        level to log at. Useful levels are ``DEBUG``, ``INFO``, ``WARNING``,
+        and ``ERROR``.
+
+.. currentmodule:: mitogen.utils
+.. function:: run_with_router(func, \*args, \**kwargs)
+
+    Arrange for `func(router, \*args, \**kwargs)` to run with a temporary
+    :py:class:`mitogen.master.Router`, ensuring the Router and Broker are
+    correctly shut down during normal or exceptional return.
+
+    :returns:
+        `func`'s return value.
+
+.. currentmodule:: mitogen.utils
+.. decorator:: with_router
+
+    Decorator version of :py:func:`run_with_router`. Example:
+
+    .. code-block:: python
+
+        @with_router
+        def do_stuff(router, arg):
+            pass
+
+        do_stuff(blah, 123)
 
 
 Exceptions
diff --git a/mitogen/utils.py b/mitogen/utils.py
index 1afd9a80..c3898c36 100644
--- a/mitogen/utils.py
+++ b/mitogen/utils.py
@@ -1,6 +1,3 @@
-"""
-A random assortment of utility functions useful on masters and slaves.
-"""
 
 import logging
 import sys
@@ -14,17 +11,12 @@ LOG = logging.getLogger('mitogen')
 
 
 def disable_site_packages():
-    """Remove all entries mentioning site-packages or Extras from the system
-    path. Used primarily for testing on OS X within a virtualenv, where OS X
-    bundles some ancient version of the 'six' module."""
     for entry in sys.path[:]:
         if 'site-packages' in entry or 'Extras' in entry:
             sys.path.remove(entry)
 
 
 def log_to_file(path=None, io=True, level='INFO'):
-    """Install a new :py:class:`logging.Handler` writing applications logs to
-    the filesystem. Useful when debugging slave IO problems."""
     log = logging.getLogger('')
     if path:
         fp = open(path, 'w', 1)
@@ -45,9 +37,6 @@ def log_to_file(path=None, io=True, level='INFO'):
 
 
 def run_with_router(func, *args, **kwargs):
-    """Arrange for `func(router, *args, **kwargs)` to run with a temporary
-    :py:class:`mitogen.master.Router`, ensuring the Router and Broker are
-    correctly shut down during normal or exceptional return."""
     broker = mitogen.master.Broker()
     router = mitogen.master.Router(broker)
     try:
@@ -58,16 +47,6 @@ def run_with_router(func, *args, **kwargs):
 
 
 def with_router(func):
-    """Decorator version of :py:func:`run_with_router`. Example:
-
-    .. code-block:: python
-
-        @with_router
-        def do_stuff(router, arg):
-            pass
-
-        do_stuff(blah, 123)
-    """
     def wrapper(*args, **kwargs):
         return run_with_router(func, *args, **kwargs)
     wrapper.func_name = func.func_name