An initial clean up of the sphinx docs.

Docstring cleanup to be implemented in a later commit.

Author: aezell

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,10 +29,10 @@ 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()

docs/source/index.rst

@@ -1,9 +1,9 @@
-.. 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:

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.