[tor-commits] [stem/master] Adding module overviews back to docs

[atagar at torproject.org]

commit 1cfad693de89bc4769605f21d52ef9ba4f38205b
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Jun 4 10:04:45 2012 -0700

    Adding module overviews back to docs
    
    One bit of documentation that I've found very useful, and sphinx lacks, is a
    brief summary of a module's contents. Hence adding that back to the headers.
---
 stem/connection.py |   14 +++++++++++++-
 stem/process.py    |    7 +++++++
 stem/version.py    |   33 ++++++++++++++++++++-------------
 3 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/stem/connection.py b/stem/connection.py
index 3f971bf..ce83068 100644
--- a/stem/connection.py
+++ b/stem/connection.py
@@ -41,8 +41,20 @@ the authentication process. For instance...
     print "Unable to authenticate: %s" % exc
     sys.exit(1)
 
-Authentication failure exception hierchy::
+**Module Overview:**
 
+::
+
+  connect_port - Convenience method to get an authenticated control connection.
+  connect_socket_file - Similar to connect_port, but for control socket files.
+  
+  authenticate - Main method for authenticating to a control socket.
+  authenticate_none - Authenticates to an open control socket.
+  authenticate_password - Authenticates to a socket supporting password auth.
+  authenticate_cookie - Authenticates to a socket supporting cookie auth.
+  
+  get_protocolinfo - Issues a PROTOCOLINFO query.
+  
   AuthenticationFailure - Base exception raised for authentication failures.
     |- UnrecognizedAuthMethods - Authentication methods are unsupported.
     |- IncorrectSocketType - Socket does not speak the tor control protocol.
diff --git a/stem/process.py b/stem/process.py
index 5df04dc..b0e5015 100644
--- a/stem/process.py
+++ b/stem/process.py
@@ -6,6 +6,13 @@ Helper functions for working with tor as a process.
 
 :DEFAULT_INIT_TIMEOUT:
   number of seconds before we time out our attempt to start a tor instance
+
+**Module Overview:**
+
+::
+
+  launch_tor             - starts up a tor process
+  launch_tor_with_config - starts a tor process with a custom torrc
 """
 
 import re
diff --git a/stem/version.py b/stem/version.py
index 925acf0..0159512 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -2,19 +2,26 @@
 Tor versioning information and requirements for its features. These can be
 easily parsed and compared, for instance...
 
->>> my_version = stem.version.get_system_tor_version()
->>> print my_version
-0.2.1.30
->>> my_version > stem.version.Requirement.CONTROL_SOCKET
-True
+::
 
-+----------------------------------------------------------+
-|Requirement                                               |
-+=====================+====================================+
-|GETINFO_CONFIG_TEXT  |'GETINFO config-text' query         |
-+---------------------+------------------------------------+
-|CONTROL_SOCKET       |'ControlSocket <path>' config option|
-+---------------------+------------------------------------+
+  >>> my_version = stem.version.get_system_tor_version()
+  >>> print my_version
+  0.2.1.30
+  >>> my_version > stem.version.Requirement.CONTROL_SOCKET
+  True
+
+**Module Overview:**
+
+::
+
+  get_system_tor_version - gets the version of our system's tor installation
+  Version - Tor versioning information.
+    |- __str__ - string representation
+    +- __cmp__ - compares with another Version
+  
+  Requirement - Enumerations for the version requirements of features.
+    |- GETINFO_CONFIG_TEXT - 'GETINFO config-text' query
+    +- CONTROL_SOCKET      - 'ControlSocket <path>' config option
 """
 
 import re