[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