Try 2: Hopefully made README.txt conform to ReST syntax.

[django-pagination.git] / README.txt

diff --git a/README.txt b/README.txt
index 06001ec..0834d6c 100644 (file)
--- a/README.txt
+++ b/README.txt
@@ -1,11 +1,60 @@
-=======================
-django-oembed
-=======================
+How to use django-pagination
+----------------------------
 
-This is a collection of tools for Django to allow for replacing links in text
-with OEmbed.  This application also provides utilities to make this process not
-prohibitively expensive CPU-wise.
+``django-pagination`` allows for easy Digg-style pagination without modifying
+your views.
 
-For installation instructions, read INSTALL.txt.
+There are really 5 steps to setting it up with your projects (not including 
+installation, which is covered in INSTALL.txt in this same directory.)
 
-Visit the google code page at http://django-oembed.googlecode.com/
\ No newline at end of file
+1. List this application in the ``INSTALLED_APPS`` portion of your settings
+   file.  Your settings file might look something like:
+   
+       INSTALLED_APPS = (
+           # ...
+           'pagination',
+       )
+
+
+2. Install the pagination middleware.  Your settings file might look something
+   like:
+   
+       MIDDLEWARE_CLASSES = (
+           # ...
+           'pagination.middleware.PaginationMiddleware',
+       )
+
+
+3. Add this line at the top of your template to load the pagination tags:
+
+       {% load pagination_tags %}
+
+
+4. Decide on a variable that you would like to paginate, and use the
+   autopaginate tag on that variable before iterating over it.  This could 
+   take one of two forms (using the canonical ``object_list`` as an example
+   variable):
+   
+       {% autopaginate object_list %}
+       
+   This assumes that you would like to have the default 20 results per page.
+   If you would like to specify your own amount of results per page, you can
+   specify that like so:
+   
+       {% autopaginate object_list 10 %}
+   
+   Note that this replaces ``object_list`` with the list for the current page, so
+   you can iterate over the ``object_list`` like you normally would.
+   
+
+5. Now you want to display the current page and the available pages, so
+   somewhere after having used autopaginate, use the paginate inclusion tag:
+   
+       {% paginate %}
+   
+   This does not take any arguments, but does assume that you have already
+   called autopaginate, so make sure to do so first.
+
+
+That's it!  You have now paginated ``object_list`` and given users of the site
+a way to navigate between the different pages--all without touching your views.
\ No newline at end of file