1 files changed, 120 insertions, 0 deletions
diff --git a/doc/build/caching.rst b/doc/build/caching.rst
index 8b13789..3ad35ff 100644
--- a/doc/build/caching.rst
+++ b/doc/build/caching.rst
@@ -1 +1,121 @@
+.. _caching_toplevel:
 
+========
+Caching
+========
+
+Any template or component can be cached using the ``cache``
+argument to the ``<%page>`` or ``<%def>`` directives:
+
+.. sourcecode:: mako
+
+    <%page cached="True"/>
+    
+    template text
+    
+The above template, after being executed the first time, will
+store its content within a cache that by default is scoped
+within memory. Subsequent calls to the template's :meth:`~.Template.render`
+method will return content directly from the cache. When the
+:class:`.Template` object itself falls out of scope, its corresponding
+cache is garbage collected along with the template.
+
+Caching requires that the ``beaker`` package be installed on the
+system.
+
+The caching flag and all its options can be used with the
+``<%def>`` tag.
+
+.. sourcecode:: mako
+
+    <%def name="mycomp" cached="True" cache_timeout="30" cache_type="memory">
+        other text
+    </%def>
+
+Cache arguments
+================
+
+The various cache arguments are cascaded from their default
+values, to the arguments specified programmatically to the
+:class:`.Template` or its originating :class:`.TemplateLookup`, then to those
+defined in the ``<%page>`` tag of an individual template, and
+finally to an individual ``<%def>`` tag within the template. This
+means you can define, for example, a cache type of ``dbm`` on your
+:class:`.TemplateLookup`, a cache timeout of 60 seconds in a particular
+template's ``<%page>`` tag, and within one of that template's
+``<%def>`` tags ``cache=True``, and that one particular def will
+then cache its data using a ``dbm`` cache and a data timeout of 60
+seconds.
+
+The options available are:
+
+* ``cached="False|True"`` - turn caching on
+* ``cache_timeout`` - number of seconds in which to invalidate the
+  cached data. after this timeout, the content is re-generated
+  on the next call.
+* ``cache_type`` - type of caching. ``memory``, ``file``, ``dbm``, or
+  ``memcached``.
+* ``cache_url`` - (only used for ``memcached`` but required) a single
+  IP address or a semi-colon separated list of IP address of
+  memcache servers to use.
+* ``cache_dir`` - In the case of the ``file`` and ``dbm`` cache types,
+  this is the filesystem directory with which to store data
+  files. If this option is not present, the value of
+  ``module_directory`` is used (i.e. the directory where compiled
+  template modules are stored). If neither option is available
+  an exception is thrown.
+  
+  In the case of the ``memcached`` type, this attribute is required
+  and it's used to store the lock files.
+* ``cache_key`` - the "key" used to uniquely identify this content
+  in the cache. the total namespace of keys within the cache is
+  local to the current template, and the default value of "key"
+  is the name of the def which is storing its data. It is an
+  evaluable tag, so you can put a Python expression to calculate
+  the value of the key on the fly. For example, heres a page
+  that caches any page which inherits from it, based on the
+  filename of the calling template:
+    
+.. sourcecode:: mako
+
+    <%page cached="True" cache_key="${self.filename}"/>
+
+    ${next.body()}
+    
+    ## rest of template
+    
+Accessing the Cache
+===================
+
+The :class:`.Template`, as well as any template-derived namespace, has
+an accessor called ``cache`` which returns the ``Cache`` object
+for that template. This object is a facade on top of the Beaker
+internal cache object, and provides some very rudimental
+capabilities, such as the ability to get and put arbitrary
+values:
+
+.. sourcecode:: mako
+
+    <%
+        local.cache.put("somekey", type="memory", "somevalue")
+    %>
+    
+Above, the cache associated with the ``local`` namespace is
+accessed and a key is placed within a memory cache.
+
+More commonly the ``cache`` object is used to invalidate cached
+sections programmatically:
+
+.. sourcecode:: python
+
+    template = lookup.get_template('/sometemplate.html')
+    
+    # invalidate the "body" of the template
+    template.cache.invalidate_body()
+    
+    # invalidate an individual def
+    template.cache.invalidate_def('somedef')
+    
+    # invalidate an arbitrary key
+    template.cache.invalidate('somekey')
+