Document a bunch of mitogen.master and move more docstrings into Sphinx.

docs/api.rst

@@ -52,7 +52,12 @@ bootstrap implementation sent to every new slave context.
 mitogen.master
 --------------
 
-.. automodule:: mitogen.master
+.. module:: mitogen.master
+
+This module implements functionality required by master processes, such as
+starting new contexts via SSH. Its size is also restricted, since it must
+be sent to any context that will be used to establish additional child
+contexts.
 
 
 mitogen.fakessh

docs/internals.rst

@@ -79,9 +79,71 @@ ExternalContext Class
 
 
 mitogen.master
-===============
+==============
 
-.. autoclass:: mitogen.master.ProcessMonitor
+.. class:: mitogen.master.ProcessMonitor
+
+    Install a :py:data:`signal.SIGCHLD` handler that generates callbacks when a
+    specific child process has exitted.
+
+    .. method:: add (pid, callback)
+
+        Add a callback function to be notified of the exit status of a process.
+
+        :param int pid:
+            Process ID to be notified of.
+
+        :param callback:
+            Function invoked as `callback(status)`, where `status` is the raw
+            exit status of the child process.
+
+
+Blocking I/O Functions
+----------------------
+
+These functions exist to support the blocking phase of setting up a new
+context. They will eventually be replaced with asynchronous equivalents.
+
+
+.. function:: mitogen.master.iter_read(fd, deadline=None)
+
+    Return a generator that arranges for up to 4096-byte chunks to be read at a
+    time from the file descriptor `fd` until the generator is destroyed.
+
+    :param fd:
+        File descriptor to read from.
+
+    :param deadline:
+        If not ``None``, an absolute UNIX timestamp after which timeout should
+        occur.
+
+    :raises mitogen.core.TimeoutError:
+        Attempt to read beyond deadline.
+
+    :raises mitogen.core.StreamError:
+        Attempt to read past end of file.
+
+
+.. function:: mitogen.master.write_all (fd, s, deadline=None)
+
+    Arrange for all of bytestring `s` to be written to the file descriptor
+    `fd`.
+
+    :param int fd:
+        File descriptor to write to.
+
+    :param bytes s:
+        Bytestring to write to file descriptor.
+
+    :param float deadline:
+        If not ``None``, an absolute UNIX timestamp after which timeout should
+        occur.
+
+    :raises mitogen.core.TimeoutError:
+        Bytestring could not be written entirely before deadline was exceeded.
+
+    :raises mitogen.core.StreamError:
+        File descriptor was disconnected before write could complete.
 
 
 Helper Functions
@@ -98,6 +160,51 @@ Helper Functions
     ECONNRESET may be triggered by any read or write.
 
 
-.. autofunction:: mitogen.master.create_child
-.. autofunction:: mitogen.master.get_child_modules
-.. autofunction:: mitogen.master.minimize_source
+.. function:: mitogen.master.create_child (\*args)
+
+    Create a child process whose stdin/stdout is connected to a socket,
+    returning `(pid, socket_obj)`.
+
+
+.. function:: mitogen.master.tty_create_child (\*args)
+
+    Return a file descriptor connected to the master end of a pseudo-terminal,
+    whose slave end is connected to stdin/stdout/stderr of a new child process.
+    The child is created such that the pseudo-terminal becomes its controlling
+    TTY, ensuring access to /dev/tty returns a new file descriptor open on the
+    slave end.
+
+    :param list args:
+        :py:func:`os.execl` argument list.
+
+    :returns:
+        `(pid, fd)`
+
+
+.. function:: mitogen.master.get_child_modules (path, fullname)
+
+    Return the canonical names of all submodules of a package `module`.
+
+    :param str path:
+        Path to the module's source code on disk, or some PEP-302-recognized
+        equivalent. Usually this is the module's ``__file__`` attribute, but
+        is specified explicitly to avoid loading the module.
+
+    :param str fullname:
+        The module's canonical name. This is the module's ``__name__``
+        attribute, but is specified explicitly to avoid loading the module.
+
+    :return:
+        List of canonical submodule names.
+
+
+.. autofunction:: mitogen.master.minimize_source (source)
+
+    Remove comments and docstrings from Python `source`, preserving line
+    numbers and syntax of empty blocks.
+
+    :param str source:
+        The source to minimize.
+
+    :returns str:
+        The minimized source.

mitogen/master.py

-"""
-This module implements functionality required by master processes, such as
-starting new contexts via SSH. Its size is also restricted, since it must be
-sent to any context that will be used to establish additional child contexts.
-"""
-
 import commands
 import errno
 import getpass
@@ -43,8 +37,6 @@ IOLOG_RE = re.compile(r'^[ ]*IOLOG.debug\(.+?\)$', re.M)
 
 
 def minimize_source(source):
-    """Remove comments and docstrings from Python `source`, preserving line
-    numbers and syntax of empty blocks."""
     subber = lambda match: '""' + ('\n' * match.group(0).count('\n'))
     source = DOCSTRING_RE.sub(subber, source)
     source = COMMENT_RE.sub('', source)
@@ -52,7 +44,6 @@ def minimize_source(source):
 
 
 def get_child_modules(path, fullname):
-    """Return the canonical names of all submodules of a package `module`."""
     it = pkgutil.iter_modules([os.path.dirname(path)])
     return ['%s.%s' % (fullname, name) for _, name, _ in it]
 
@@ -67,8 +58,6 @@ def format_cmdline(args):
 
 
 def create_child(*args):
-    """Create a child process whose stdin/stdout is connected to a socket,
-    returning `(pid, socket_obj)`."""
     parentfp, childfp = socket.socketpair()
     pid = os.fork()
     if not pid:
@@ -126,16 +115,6 @@ def close_nonstandard_fds():
 
 
 def tty_create_child(*args):
-    """
-    Return a file descriptor connected to the master end of a pseudo-terminal,
-    whose slave end is connected to stdin/stdout/stderr of a new child process.
-    The child is created such that the pseudo-terminal becomes its controlling
-    TTY, ensuring access to /dev/tty returns a new file descriptor open on the
-    slave end.
-
-    :param args:
-        execl() arguments.
-    """
     master_fd, slave_fd = os.openpty()
     disable_echo(master_fd)
     disable_echo(slave_fd)