[tor-commits] [stem/master] Converting stem.version to reStructuredText

[atagar at torproject.org]

commit ecc0e86d46ac2db77d45d46af5ac50168befa6c9
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Jun 3 16:18:00 2012 -0700

    Converting stem.version to reStructuredText
---
 docs/conf.py    |    3 +--
 docs/index.rst  |    5 +++++
 stem/version.py |   54 +++++++++++++++++++++++-------------------------------
 3 files changed, 29 insertions(+), 33 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index d07c0cc..a9d4b7d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -28,8 +28,7 @@ needs_sphinx = '1.1' # required for the sphinx-apidoc command
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
 
-autoclass_content = 'both'
-autodoc_member_order = 'groupwise'
+autodoc_member_order = 'bysource'
 autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members']
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/index.rst b/docs/index.rst
index 6cf06ea..c735bf6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,11 @@ Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Li
 
 Used for launching Tor and managing the process.
 
+:mod:`stem.version`
+-------------------
+
+Parsed versions that can be compared to the requirement for various features.
+
 .. toctree::
    :maxdepth: 2
 
diff --git a/stem/version.py b/stem/version.py
index eb0f707..925acf0 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -8,14 +8,13 @@ easily parsed and compared, for instance...
 >>> my_version > stem.version.Requirement.CONTROL_SOCKET
 True
 
-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
++----------------------------------------------------------+
+|Requirement                                               |
++=====================+====================================+
+|GETINFO_CONFIG_TEXT  |'GETINFO config-text' query         |
++---------------------+------------------------------------+
+|CONTROL_SOCKET       |'ControlSocket <path>' config option|
++---------------------+------------------------------------+
 """
 
 import re
@@ -31,14 +30,11 @@ def get_system_tor_version(tor_cmd = "tor"):
   Queries tor for its version. This is os dependent, only working on linux,
   osx, and bsd.
   
-  Arguments:
-    tor_cmd (str) - command used to run tor
+  :param str tor_cmd: command used to run tor
   
-  Returns:
-    stem.version.Version provided by the tor command
+  :returns: :class:`stem.version.Version` provided by the tor command
   
-  Raises:
-    IOError if unable to query or parse the version
+  :raises: IOError if unable to query or parse the version
   """
   
   if not tor_cmd in VERSION_CACHE:
@@ -70,27 +66,23 @@ def get_system_tor_version(tor_cmd = "tor"):
 
 class Version:
   """
-  Comparable tor version, as per the 'new version' of the version-spec...
-  https://gitweb.torproject.org/torspec.git/blob/HEAD:/version-spec.txt
+  Comparable tor version. These are constructed from strings that conform to
+  the 'new' style in the `tor version-spec
+  <https://gitweb.torproject.org/torspec.git/blob/HEAD:/version-spec.txt>`_,
+  such as "0.1.4" or "0.2.2.23-alpha (git-7dcd105be34a4f44)".
+  
+  :var int major: major version
+  :var int minor: minor version
+  :var int micro: micro version
+  :var int patch: optional patch level (None if undefined)
+  :var str status: optional status tag without the preceding dash such as 'alpha', 'beta-dev', etc (None if undefined)
   
-  Attributes:
-    major (int)  - major version
-    minor (int)  - minor version
-    micro (int)  - micro version
-    patch (int)  - optional patch level (None if undefined)
-    status (str) - optional status tag without the preceding dash such as
-                   'alpha', 'beta-dev', etc (None if undefined)
+  :param str version_str: version to be parsed
+  
+  :raises: ValueError if input isn't a valid tor version
   """
   
   def __init__(self, version_str):
-    """
-    Parses a valid tor version string, for instance "0.1.4" or
-    "0.2.2.23-alpha (git-7dcd105be34a4f44)".
-    
-    Raises:
-      ValueError if input isn't a valid tor version
-    """
-    
     self.version_str = version_str
     m = re.match(r'^([0-9]+)\.([0-9]+)\.([0-9]+)(\.[0-9]+)?(-\S*)?$', version_str)