[tor-commits] [stem/master] Only including prepared API docs

atagar at torproject.org atagar at torproject.org
Sun Oct 28 20:56:34 UTC 2012


commit 0cc97d2dcc15ce227983cfc72c234bf995b4857a
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Oct 21 20:04:30 2012 -0700

    Only including prepared API docs
    
    Our sphinx-apidoc made it so all our pydocs were included in our built
    documentation. This is great, except that those documentation dumps are
    completely unreadable. Dropping the sphinx-apidoc call in favor of including
    specific autodoc pages we've prepared.
    
    Made some revisions to stem.version's documentation and including that to
    start.
---
 docs/Makefile          |    2 --
 docs/api.rst           |   44 +++-----------------------------------------
 docs/conf.py           |    9 ---------
 docs/index.rst         |    4 ----
 docs/types/version.rst |    5 +++++
 stem/version.py        |   37 +++++++++++++++++--------------------
 6 files changed, 25 insertions(+), 76 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 22f3516..e0febbd 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -38,8 +38,6 @@ clean:
 	@rm -f ./stem.* ./modules.rst
 
 html:
-	@sphinx-apidoc -f -o /tmp/stem_docs ../stem
-	@rsync --size-only /tmp/stem_docs/* .
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/docs/api.rst b/docs/api.rst
index 0e71afa..3015210 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -1,46 +1,8 @@
 API
 ===
 
-:mod:`stem.connection`
-----------------------
+Types
+-----
 
-Connecting and authenticating to a Tor process.
-
-:mod:`stem.control`
--------------------
-
-Provides the :class:`~stem.control.Controller` class which, as the name implies, is used for talking with and controlling a Tor instance. As a user this is the primary class that you'll need.
-
-:mod:`stem.socket`
-------------------
-
-Base classes for communicating with a Tor control socket.
-
-:mod:`stem.process`
--------------------
-
-Used for launching Tor and managing the process.
-
-:mod:`stem.version`
--------------------
-
-Parsed versions that can be compared to the requirement for various features.
-
-`stem.descriptor <stem.descriptor.html>`_
------------------------------------------
-
-Utilities for working with the Tor consensus and descriptors.
-
-`stem.response <stem.response.html>`_
--------------------------------------
-
-Parsed replies that we receive from the Tor control socket.
-
-`stem.util <stem.util.html>`_
------------------------------
-
-Utility functions available to stem and its users.
-
-.. toctree::
-   :maxdepth: 2
+* `stem.version <types/version.html>`_ - Tor versions that can be compared to determine Tor's capablilites.
 
diff --git a/docs/conf.py b/docs/conf.py
index 0bdd83c..ada61ec 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,15 +13,6 @@
 
 import sys, os
 
-# Our make file calls sphinx-apidoc, but read-the-docs uses our config instead
-# (so it skips that step). Calling apidoc here instead if we're being built
-# there.
-
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
-if on_rtd:
-  os.system("sphinx-apidoc -f -o . ../stem")
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
diff --git a/docs/index.rst b/docs/index.rst
index 95c1589..aa5ab03 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,7 +21,3 @@ Indices and tables
 
 *Last updated:* |today|
 
-
-
-
-
diff --git a/docs/types/version.rst b/docs/types/version.rst
new file mode 100644
index 0000000..ad9e875
--- /dev/null
+++ b/docs/types/version.rst
@@ -0,0 +1,5 @@
+Version
+=======
+
+.. automodule:: stem.version
+
diff --git a/stem/version.py b/stem/version.py
index 342c400..bb75c18 100644
--- a/stem/version.py
+++ b/stem/version.py
@@ -4,10 +4,11 @@ easily parsed and compared, for instance...
 
 ::
 
-  >>> my_version = stem.version.get_system_tor_version()
+  >>> from stem.version import get_system_tor_version, Requirement
+  >>> my_version = get_system_tor_version()
   >>> print my_version
   0.2.1.30
-  >>> my_version.meets_requirements(stem.version.Requirement.CONTROL_SOCKET)
+  >>> my_version.meets_requirements(Requirement.CONTROL_SOCKET)
   True
 
 **Module Overview:**
@@ -48,9 +49,9 @@ def get_system_tor_version(tor_cmd = "tor"):
   
   :param str tor_cmd: command used to run tor
   
-  :returns: :class:`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:
@@ -90,14 +91,14 @@ class Version(object):
   :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)
-  :var str extra: optional extra information without the proceeding space nor its parentheses such as 'git-8be6058d8f31e578' (None if undefined)
-  :var str git_commit: optional git commit id (None if it wasn't provided)
+  :var int patch: patch level (**None** if undefined)
+  :var str status: status tag such as 'alpha' or 'beta-dev' (**None** if undefined)
+  :var str extra: extra information without its parentheses such as 'git-8be6058d8f31e578' (**None** if undefined)
+  :var str git_commit: git commit id (**None** if it wasn't provided)
   
   :param str version_str: version to be parsed
   
-  :raises: ValueError if input isn't a valid tor version
+  :raises: **ValueError** if input isn't a valid tor version
   """
   
   def __init__(self, version_str):
@@ -129,10 +130,9 @@ class Version(object):
   
   def meets_requirements(self, requirements):
     """
-    Checks if this version meets the requirements for a given feature.
-    
-    Requirements can be either a :class:`stem.version.Version` or
-    :class:`stem.version.VersionRequirements`.
+    Checks if this version meets the requirements for a given feature. We can
+    be compared to either a :class:`~stem.version.Version` or
+    :class:`~stem.version.VersionRequirements`.
     
     :param requirements: requrirements to be checked for
     """
@@ -147,15 +147,14 @@ class Version(object):
   
   def __str__(self):
     """
-    Provides the string used to construct the Version.
+    Provides the string used to construct the version.
     """
     
     return self.version_str
   
   def __cmp__(self, other):
     """
-    Simple comparison of versions. An undefined patch level is treated as zero
-    and status tags are not included in comparisions (as per the version spec).
+    Compares version ordering according to the spec.
     """
     
     if not isinstance(other, Version):
@@ -182,17 +181,15 @@ class Version(object):
 
 class VersionRequirements(object):
   """
-  Series of version constraints that can be compared to. For instance, it
+  Series of version constraints that can be compared to. For instance, this
   allows for comparisons like 'if I'm greater than version X in the 0.2.2
   series, or greater than version Y in the 0.2.3 series'.
   
   This is a logical 'or' of the series of rules.
   """
   
-  def __init__(self, rule = None):
+  def __init__(self):
     self.rules = []
-    
-    if rule: self.greater_than(rule)
   
   def greater_than(self, version, inclusive = True):
     """





More information about the tor-commits mailing list