Refactored the docs a bit to be more pleasant to read.

README.rst

@@ -41,8 +41,3 @@ header from response when it updates the cache is also included, which, if
 used in place of the standard UpdateCacheMiddleware will prevent the cache
 middleware from varying the cache key based on cookies, thus enabling caching
 of pages in authenticated sessions.
-
-Documentation lives in the ``docs`` directory as Sphinx documentation or
-`in HTML rendered form here`_.
-
-.. _`in HTML rendered form here`: http://django-phased.readthedocs.org/en/latest/

docs/index.rst

@@ -1,14 +1,13 @@
-django-phased
-=============
+.. include:: ../README.rst
 
 .. toctree::
    :maxdepth: 2
 
    tutorial
-   middleware
    settings
-   utils
+   middleware
    templatetag
+   utils
    changelog
 
 Indices and tables

docs/middleware.rst

@@ -4,17 +4,11 @@
 Middleware
 ==========
 
-django-phased provides two helpful middleware classes, `PhasedRenderMiddleware`
-and `PatchedVaryUpdateCacheMiddleware`.
-
-PhasedRenderMiddleware
-======================
+django-phased provides two helpful middleware classes,
+``PhasedRenderMiddleware`` and ``PatchedVaryUpdateCacheMiddleware``.
 
 .. autoclass:: phased.middleware.PhasedRenderMiddleware
     :members: process_response
 
-PatchedVaryUpdateCacheMiddleware
-================================
-
 .. autoclass:: phased.middleware.PatchedVaryUpdateCacheMiddleware
     :members: process_response

docs/templatetag.rst

@@ -7,6 +7,5 @@ Template tag
 .. highlight:: django
 
 .. autofunction:: phased.templatetags.phased_tags.phased
-.. autofunction:: phased.templatetags.phased_tags.parse
-
 .. autofunction:: phased.templatetags.phased_tags.phasedcache
+.. autofunction:: phased.templatetags.phased_tags.parse

docs/tutorial.rst

@@ -1,8 +1,8 @@
 .. _ref-tutorial:
 
-==================================
-Getting Started with django-phased
-==================================
+==========
+Quickstart
+==========
 
 django-phased is an implementation of a two-phase template rendering system
 to allow caching of pages that otherwise would be uncachable due to
@@ -17,33 +17,39 @@ Installation
 To install django-phased, either check out the source from Github or install
 from PyPI_:
 
-  * Check out django-phased from GitHub_ and run `python setup.py install`
-    in the source checkout, or
+* Check out django-phased from GitHub_ and run ``python setup.py install``
+  in the source checkout
 
-  * Run ``pip install django-phased``.
+  or
+
+* Run ``pip install django-phased``.
 
 .. _GitHub: http://github.com/codysoyland/django-phased
 .. _PyPI: http://pypi.python.org/
 
 
-Configuration
-=============
+Setup
+=====
 
 To make django-phased tags available to your templates, add ``'phased'`` to
 your ``INSTALLED_APPS``.
 
-You can either use ``phased`` via the ``PhasedRenderMiddleware``
-middleware or via the ``phasedcache`` template tag.
+You can either use ``phased`` via the
+:ref:`PhasedRenderMiddleware <ref-middleware>` middleware or the
+:attr:`~phased.templatetags.phased_tags.phasedcache` template tag.
+
+Usage
+=====
 
 Middleware
 ----------
 
-Install :class:`phased.middleware.PhasedRenderMiddleware` to enable
+Install the :class:`~phased.middleware.PhasedRenderMiddleware` to enable
 second-phase rendering of templates.
 
 If using Django's caching middleware, use
-:class:`phased.middleware.PatchedVaryUpdateCacheMiddleware` to bypass the
-Vary: Cookie behavior of that middleware.
+:class:`~phased.middleware.PatchedVaryUpdateCacheMiddleware` to bypass the
+``Vary: Cookie`` behavior of that middleware.
 
 A common setup for middleware classes would be this:
 
@@ -58,15 +64,21 @@ A common setup for middleware classes would be this:
 
 See :doc:`settings` for additional settings.
 
-
 Template Tag
 ------------
 
 In order to use the ``phasedcache`` template tag you need to add
-``'django.core.context_processors.request'`` to the ``TEMPLATE_CONTEXT_PROCESSORS``
-settingsvariable and use ``RequestContext`` when you render your templates.
+``'django.core.context_processors.request'`` to the
+``TEMPLATE_CONTEXT_PROCESSORS`` settings variable and use ``RequestContext``
+when you render your templates. See the Django docs on
+`how to use RequestContext`_ in your views.
+
+The ``phasedcache`` template tag works exactly like Django's
+`cache template tag`_ except that it will run a second render pass using the
+:attr:`~phased.utils.second_pass_render` function with value returned
+from the cache.
 
-The ``phasedcache`` template tag works exactly like the Django's ``cache`` template
-tag except that it will do a second render pass.
+See :attr:`~phased.templatetags.phased_tags.phasedcache` for details.
 
-See :class:`phased.templatetags.phased_tags.phasedcache` for details.
+.. _`how to use RequestContext`: https://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext
+.. _`cache template tag`: https://docs.djangoproject.com/en/dev/topics/cache/#template-fragment-caching

phased/middleware.py

@@ -5,14 +5,16 @@
 
 class PhasedRenderMiddleware(object):
     """
-    Performs a second-phase template rendering on the response. Should be
-    placed before the UpdateCacheMiddleware.
+    Performs a second-phase template rendering on the response and should be
+    placed before the UpdateCacheMiddleware
+    (or :class:`~phased.middleware.PatchedVaryUpdateCacheMiddleware`) in the
+    ``MIDDLEWARE_CLASES`` setting.
     """
     def process_response(self, request, response):
         """
-        If the content-type is "text/html", perform second-phase render on
-        response.content and update response['Content-Length'] to reflect
-        change in size after rendering.
+        If the content-type starts with ``text/html`` performs a second-phase
+        render on response.content and updates the ``Content-Length`` header
+        of the response to reflect the change in size after rendering.
         """
         if not response['content-type'].startswith("text/html"):
             return response
@@ -23,17 +25,18 @@ def process_response(self, request, response):
 
 class PatchedVaryUpdateCacheMiddleware(UpdateCacheMiddleware):
     """
-    If "Vary: Cookie" is set in the response object, Django's cache middleware
-    will vary the cache key based on the value of the cookie.  This subclass
-    of django's UpdateCacheMiddleware is designed to cache without varying the
-    cache key on cookie contents.
+    If ``Vary: Cookie`` is set in the response object, Django's cache
+    middleware will vary the cache key based on the value of the cookie.
+
+    This subclass of Django's UpdateCacheMiddleware is designed to cache
+    without varying the cache key on cookie contents.
     """
     def process_response(self, request, response):
         """
-        This removes the "Vary: Cookie" header prior to running the standard
-        Django UpdateCacheMiddleware.process_response() and adds the header
-        back after caching so that in-browser caches are aware to vary the
-        cache on cookie.
+        This removes the ``Vary: Cookie`` header prior to running the standard
+        Django ``UpdateCacheMiddleware.process_response()`` and adds the
+        header back after caching so that in-browser caches are aware to vary
+        the cache on cookies.
         """
         drop_vary_headers(response, ['Cookie'])
         response = super(PatchedVaryUpdateCacheMiddleware, self).process_response(request, response)