Merge remote branch 'aezell/pycon_sprint_docs_rewrite' into updated_docs

Author: Matt George

docs/source/class.rst

@@ -4,17 +4,25 @@ ResQ Classes
 ==========================================
 
 .. autoclass:: pyres.ResQ
-   :members:
-
+	:members:
 
 Job Classes
 =================
 
 .. autoclass:: pyres.job.Job
-   :members:
+	:members:
 
 Worker Classes
 =================
 
 .. autoclass:: pyres.worker.Worker
-   :members:
+	:members:
+
+Failure Classes
+=================
+
+.. autoclass:: pyres.failure.base.BaseBackend
+	:members:
+	
+.. autoclass:: pyres.failure.RedisBackend
+	:members:

docs/source/conf.py

@@ -12,6 +12,7 @@
 # serve to show the default.
 
 import sys, os
+from pyres import __version__
 
 # 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
@@ -37,17 +38,17 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'PyRes'
+project = u'pyres'
 copyright = u'2010, Matt George'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.4.1'
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = '0.4.1'
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -158,7 +159,7 @@
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'PyResdoc'
+htmlhelp_basename = 'pyresdoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -172,7 +173,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'PyRes.tex', u'PyRes Documentation',
+  ('index', 'pyres.tex', u'pyres Documentation',
    u'Matt George', 'manual'),
 ]
 

docs/source/example.rst

@@ -1,10 +1,9 @@
-=========
- EXAMPLE
+Example
 =========
 
 Let's take a real wold example of a blog where comments need to be checked for
-spam check. When the comment is saved in the database, we create a job in the
-queue with comment data. Let's take a django model in this case.
+spam. When the comment is saved in the database, we create a job in the
+queue with that comment data. Let's take a django model in this case.
 
 .. code-block:: python
    :linenos:
@@ -30,14 +29,14 @@ queue with comment data. Let's take a django model in this case.
                 comment.spam = False
             comment.save()
 
-You can convert your existing class to be compatible with Pyres. All you need 
-to do is add a @queue@ variable and define a @perform@ method on the class. 
+You can convert your existing class to be compatible with pyres. All you need 
+to do is add a :attr:`queue` attribute and define a :meth:`perform` method on the class. 
 
-To insert a job into the queue you need to do something like this:::
+To insert a job into the queue you need to do something like this::
 
-    from pyres import ResQ
-    r = Resq()
-    r.enqueue(Spam, 23)   # Passing the comment id 23
+    >>> from pyres import ResQ
+    >>> r = Resq()
+    >>> r.enqueue(Spam, 23)   # Passing the comment id 23
 
 This puts a job into the queue **Spam**. Now we need to fire off our workers. 
 In the **scripts** folder there is an executable::

docs/source/index.rst

@@ -1,21 +1,23 @@
-.. PyRes documentation master file, created by
+.. pyres documentation master file, created by
    sphinx-quickstart on Wed Jan  6 15:11:19 2010.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PyRes's documentation!
+Welcome to pyres's documentation!
 =================================
 
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+	:maxdepth: 2
+
+	intro
+	install
+	example
+	class
+	tests
+	failures
 
-   intro
-   install
-   example
-   class
-   tests
 
 Indices and tables
 ==================

docs/source/install.rst

@@ -1,26 +1,41 @@
 Installation
 ===============
 
-Requirements:
---------------
-simplejson>=2.0.9
-itty>=0.6.2
-redis>=0.6.0
-pystache>=0.1.0
+Pyres is most easily installed using pip and can be found on PyPI as pyres_.
 
-Make sure you install these requirements before proceeding. 
+Using ``pip install pyres`` will install the required versions of the above packages/modules. 
+Those requirements are currently:
 
-.. todo:: Need to point to notes on redis installation and get python-redis.
+::
 
-
-To install pyres.::
+	simplejson==2.0.9 
+	itty==0.6.4
+	redis==1.34.1 
+	pystache==0.2.0
+	
+If you'd rather install from the git repository, that's easy too::
 
     $ git clone git://github.com/binarydud/pyres.git
     $ cd pyres
     $ python setup.py build
     $ python setup.py install
 
-Might need to run as sudo to install.
+Of course, you'll need to install the Redis server as well. Below is a simple example, but 
+please read `Redis's own documentation`_ for more details.
+
+::
+
+	$ wget http://redis.googlecode.com/files/redis-1.2.2.tar.gz
+	$ tar -xvf redis-1.2.2.tar.gz
+	$ cd redis-1.2.2
+	$ make 
+	$ ./redis-server
+	
+This will install and start a Redis server with the default config running on port 6379. 
+This default config is good enough for you to run the pyres tests.
+
+.. _pyres: http://pypi.python.org/pypi/pyres/
+.. _Redis's own documentation: http://code.google.com/p/redis/wiki/index?tm=6
 
 
 

docs/source/intro.rst

@@ -1,14 +1,17 @@
 Introduction
 ============
 
-PyRes is a resque_ clone built in python. Resque is used by Github as their 
-message queue. Read_ the blog post from github about how they use resque in 
-production. 
+Pyres is a resque_ clone built in python. Resque is used by Github as their 
+message queue. Both use Redis_ as the queue backend and provide a web-based
+monitoring application. 
 
-:synopsis: Any job which takes a little while to run can be put on a message 
-queue. Read our :doc:`Example </example>` implementation of how a PyRes can be used to spam check comments.
+Read_ the blog post from github about how they use resque in production. 
+
+:synopsis: Put jobs (which can be any kind of class) on a queue and process them while watching the progress via your browser.
+
+Read our :doc:`example implementation </example>` of how pyres can be used to spam check comments.
 
 
 .. _resque: http://github.com/defunkt/resque#readme
 .. _Read: http://github.com/blog/542-introducing-resque
-
+.. _Redis: http://code.google.com/p/redis/

docs/source/tests.rst

@@ -1,14 +1,28 @@
 Tests
 =======
 
-PyRes comes with a test suite which connects to a local redis server and 
-creates a couple of *Queues* and *jobs*. 
+Pyres comes with a test suite which connects to a local Redis server and 
+creates a couple of *queues* and *jobs*. 
 
-To run tests make sure you have nose_ installed.::
+Make sure you have nose_ installed::
 
-    $ easy_install nose
-    $ redis-server [PATH_TO_YOUR_REDIS_CONFIG]
-    $ nosetests
+    $ pip install nose
+
+Also make sure your Redis server is running::
+
+	$ cd path_to_redis_installation
+	$ ./redis-server [PATH_TO_YOUR_REDIS_CONFIG]
+	
+If you don't give the ``./redis-server`` command the config path, it will use a default config, which should run the tests just fine.
+
+Now, we're ready to run the tests. From the pyres install directory::
+
+	$ nosetests
+	............................................
+	----------------------------------------------------------------------
+	Ran 44 tests in 0.901s
+
+	OK
 
 Add **-v** flag if you want verbose output.
 

pyres/__init__.py

@@ -4,13 +4,15 @@
 import pyres.json_parser as json
 
 def my_import(name):
+    """Helper function for walking import calls when searching for classes by string names."""
     mod = __import__(name)    
     components = name.split('.')    
     for comp in components[1:]:        
         mod = getattr(mod, comp)    
     return mod
 
 def safe_str_to_class(s):
+    """Helper function to map string class names to module classes."""
     lst = s.split(".")
     klass = lst[-1]
     mod_list = lst[:-1]
@@ -25,6 +27,7 @@ def safe_str_to_class(s):
         return None
 
 def str_to_class(s):
+    """Alternate helper function to map string class names to module classes."""
     lst = s.split(".")
     klass = lst[-1]
     mod_list = lst[:-1]
@@ -39,8 +42,22 @@ def str_to_class(s):
         return None
 
 class ResQ(object):
-    """ResQ class which defines the Queue object to enqueue jobs into various
-    queues.
+    """The ResQ class defines the Redis server object to which we will
+    enqueue jobs into various queues.
+    
+    The ``__init__`` takes these keyword arguments:
+    
+        ``server`` -- IP address and port of the Redis server to which you want to connect. Default is `localhost:6379`.
+    
+        ``password`` -- The password, if required, of your Redis server. Default is "None".
+    
+        ``timeout`` -- The timeout keyword is in the signature, but is unused. Default is "None".
+    
+        ``retry_connection`` -- This keyword is in the signature but is deprecated. Default is "True".
+    
+    
+    Both ``timeout`` and ``retry_connection`` will be removed as the python-redis client
+    no longer uses them. 
     
     Example usage::
 
@@ -52,8 +69,9 @@ class ResQ(object):
 
         >>>> r.enqueue(SomeClass, args)
 
-    SomeClass can be any python class with *perform* method and a *queue* 
+    SomeClass can be any python class with a *perform* method and a *queue* 
     attribute on it.
+    
     """
     def __init__(self, server="localhost:6379", password=None, 
                  timeout=None, retry_connection=True):
@@ -110,9 +128,9 @@ def _set_redis(self, server):
     redis = property(_get_redis, _set_redis)
 
     def enqueue(self, klass, *args):
-        """
-        Enqueue a job into a specific queue. Make sure the class you are passing
+        """Enqueue a job into a specific queue. Make sure the class you are passing
         has **queue** attribute and a **perform** method on it.
+        
         """
         queue = getattr(klass,'queue', None)
         #print cls._res
@@ -128,9 +146,9 @@ def queues(self):
         return self.redis.smembers("resque:queues") or []
 
     def info(self):
-        """
-        Returns a dictionary of the current status of the pending jobs, 
+        """Returns a dictionary of the current status of the pending jobs, 
         processed, no. of queues, no. of workers, no. of failed jobs.
+        
         """
         pending = 0
         for q in self.queues():
@@ -170,8 +188,8 @@ def remove_queue(self, queue):
         del self.redis['resque:queue:%s' % queue]
 
     def close(self):
-        """
-        close the underlying redis connection
+        """Close the underlying redis connection.
+        
         """
         self.redis.disconnect()
 
@@ -198,8 +216,8 @@ def _enqueue(cls, klass, *args):
             #Job.create(queue, klass,*args)
 
 class Stat(object):
-    """
-    A Stat class which shows the current status of the queue.
+    """A Stat class which shows the current status of the queue.
+    
     """
     def __init__(self, name, resq):
         self.name = name

pyres/extensions.py

@@ -8,6 +8,7 @@
 
 from pyres.exceptions import NoQueueError
 from pyres.worker import Worker
+
 class JuniorWorker(Worker):
     def work(self, interval=5):
         self.startup()

pyres/failure/__init__.py

@@ -2,7 +2,9 @@
 from pyres import ResQ 
 import sys, traceback
 from pyres.failure.redis import RedisBackend
+
 _backend = RedisBackend
+
 def create(*args, **kwargs):
     return _backend(*args, **kwargs)