[tor-commits] [stem/master] Revised API docs for stem.process

[atagar at torproject.org]

commit d2cd6ccb0c9df470478278e570f732beec973df6
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Oct 27 18:42:32 2012 -0700

    Revised API docs for stem.process
---
 docs/api.rst         |    1 +
 docs/api/process.rst |    5 +++++
 docs/contents.rst    |    1 +
 stem/process.py      |   34 +++++++++++++++++++++-------------
 4 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 223b5bc..c138240 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -9,6 +9,7 @@ Controller
  * `stem.control <api/control.html>`_ - **Controller used to talk with Tor**.
  * `stem.connection <api/connection.html>`_ - Connection and authentication to the Tor control port or socket.
  * `stem.socket <api/socket.html>`_ - Low level control socket used to talk with Tor.
+ * `stem.process <api/process.html>`_ - Launcher for the Tor process.
 
 * **Types**
 
diff --git a/docs/api/process.rst b/docs/api/process.rst
new file mode 100644
index 0000000..0e87abf
--- /dev/null
+++ b/docs/api/process.rst
@@ -0,0 +1,5 @@
+Tor Process
+===========
+
+.. automodule:: stem.process
+
diff --git a/docs/contents.rst b/docs/contents.rst
index 6c19f33..03274a4 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -11,6 +11,7 @@ Contents
    api/control
    api/connection
    api/socket
+   api/process
 
    api/exit_policy
    api/version
diff --git a/stem/process.py b/stem/process.py
index 04f787a..25ff88a 100644
--- a/stem/process.py
+++ b/stem/process.py
@@ -39,19 +39,23 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce
   while. Usually this is done in 50 seconds or so, but occasionally calls seem
   to get stuck, taking well over the default timeout.
   
-  Note: Timeout argument does not work on Windows (`ticket
+  Note: The timeout argument does not work on Windows (`ticket
   <https://trac.torproject.org/5783>`_)
   
   :param str tor_cmd: command for starting tor
   :param list args: additional arguments for tor
   :param str torrc_path: location of the torrc for us to use
-  :param int completion_percent: percent of bootstrap completion at which this'll return
-  :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it
-  :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None
+  :param int completion_percent: percent of bootstrap completion at which
+    this'll return
+  :param functor init_msg_handler: optional functor that will be provided with
+    tor's initialization stdout as we get it
+  :param int timeout: time after which the attempt to start tor is aborted, no
+    timeouts are applied if **None**
   
-  :returns: subprocess.Popen instance for the tor subprocess
+  :returns: **subprocess.Popen** instance for the tor subprocess
   
-  :raises: OSError if we either fail to create the tor process or reached a timeout without success
+  :raises: **OSError** if we either fail to create the tor process or reached a
+    timeout without success
   """
   
   if stem.util.system.is_windows():
@@ -138,19 +142,23 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce
 
 def launch_tor_with_config(config, tor_cmd = "tor", completion_percent = 100, init_msg_handler = None, timeout = DEFAULT_INIT_TIMEOUT):
   """
-  Initializes a tor process, like :func:`stem.process.launch_tor`, but with a
+  Initializes a tor process, like :func:`~stem.process.launch_tor`, but with a
   customized configuration. This writes a temporary torrc to disk, launches
   tor, then deletes the torrc.
   
-  :param dict config: configuration options, such as ``{"ControlPort": "9051"}``
+  :param dict config: configuration options, such as '{"ControlPort": "9051"}'
   :param str tor_cmd: command for starting tor
-  :param int completion_percent: percent of bootstrap completion at which this'll return
-  :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it
-  :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None
+  :param int completion_percent: percent of bootstrap completion at which
+    this'll return
+  :param functor init_msg_handler: optional functor that will be provided with
+    tor's initialization stdout as we get it
+  :param int timeout: time after which the attempt to start tor is aborted, no
+    timeouts are applied if **None**
   
-  :returns: subprocess.Popen instance for the tor subprocess
+  :returns: **subprocess.Popen** instance for the tor subprocess
   
-  :raises: OSError if we either fail to create the tor process or reached a timeout without success
+  :raises: **OSError** if we either fail to create the tor process or reached a
+    timeout without success
   """
   
   torrc_path = tempfile.mkstemp(prefix = "torrc-", text = True)[1]