commit 0cc97d2dcc15ce227983cfc72c234bf995b4857a Author: Damian Johnson atagar@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): """