Add paragraph-level version information markup from Sphinx

(``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::``),
update docs CSS to put those infos into boxes.

9 files changed, 91 insertions, 43 deletions

diff --git a/doc/build/caching.rst b/doc/build/caching.rst
index e2d11d2..54a3d0f 100644
--- a/doc/build/caching.rst
+++ b/doc/build/caching.rst
@@ -90,7 +90,8 @@ caching can be configured using these arguments:
 * ``cache_impl`` - The string name of the cache backend
   to use.   This defaults to ``'beaker'``, which has historically
   been the only cache backend supported by Mako.
-  New in 0.6.0.
+
+  .. versionadded:: 0.6.0
 
   For example, here's how to use the upcoming
   `dogpile.cache <http://dogpilecache.readthedocs.org>`_
@@ -106,7 +107,9 @@ caching can be configured using these arguments:
 
 * ``cache_args`` - A dictionary of cache parameters that
   will be consumed by the cache backend.   See
-  :ref:`beaker_backend` for examples.  New in 0.6.0.
+  :ref:`beaker_backend` for examples.
+
+  .. versionadded:: 0.6.0
 
 Backend-Specific Cache Arguments
 --------------------------------
@@ -132,7 +135,9 @@ When using Beaker, new implementations will want to make usage
 of **cache regions** so that cache configurations can be maintained
 externally to templates.  These configurations live under
 named "regions" that can be referred to within templates themselves.
-Support for Beaker cache regions is new in Mako 0.6.0.
+
+.. versionadded:: 0.6.0
+   Support for Beaker cache regions.
 
 For example, suppose we would like two regions.  One is a "short term"
 region that will store content in a memory-based dictionary,
diff --git a/doc/build/defs.rst b/doc/build/defs.rst
index bd3aa08..31798d4 100644
--- a/doc/build/defs.rst
+++ b/doc/build/defs.rst
@@ -446,9 +446,11 @@ invoked via ``<%namespacename:defname>`` or ``<%call>``.
 Using Blocks
 ============
 
-The ``<%block>`` tag is new as of Mako 0.4.1, and introduces some new twists on the
+The ``<%block>`` tag introduces some new twists on the
 ``<%def>`` tag which make it more closely tailored towards layout.
 
+.. versionadded:: 0.4.1
+
 An example of a block:
 
 .. sourcecode:: mako
diff --git a/doc/build/filtering.rst b/doc/build/filtering.rst
index 5be010c..3bcb25a 100644
--- a/doc/build/filtering.rst
+++ b/doc/build/filtering.rst
@@ -23,8 +23,11 @@ The built-in escape flags are:
 * ``u`` : URL escaping, provided by
   ``urllib.quote_plus(string.encode('utf-8'))``
 * ``h`` : HTML escaping, provided by
-  ``markupsafe.escape(string)`` (new as of 0.3.4 -- prior
-  versions use ``cgi.escape(string, True)``)
+  ``markupsafe.escape(string)``
+
+  .. versionadded:: 0.3.4
+     Prior versions use ``cgi.escape(string, True)``.
+
 * ``x`` : XML escaping
 * ``trim`` : whitespace trimming, provided by ``string.strip()``
 * ``entity`` : produces HTML entity references for applicable
@@ -280,8 +283,9 @@ The above call is equivalent to the unbuffered call:
 Decorating
 ==========
 
-This is a feature that's new as of version 0.2.5. Somewhat like
-a filter for a ``%def`` but more flexible, the ``decorator``
+.. versionadded:: 0.2.5
+
+Somewhat like a filter for a ``%def`` but more flexible, the ``decorator``
 argument to ``%def`` allows the creation of a function that will
 work in a similar manner to a Python decorator. The function can
 control whether or not the function executes. The original
diff --git a/doc/build/runtime.rst b/doc/build/runtime.rst
index ff71fe8..17c9b99 100644
--- a/doc/build/runtime.rst
+++ b/doc/build/runtime.rst
@@ -80,12 +80,14 @@ automatically correspond to what was passed into the current
   it, which is what happens if you try to use it in an
   expression.
 * **UNDEFINED makes it hard for me to find what name is missing** - An alternative
-  introduced in version 0.3.6 is to specify the option
-  ``strict_undefined=True``
+  is to specify the option ``strict_undefined=True``
   to the :class:`.Template` or :class:`.TemplateLookup`.  This will cause
   any non-present variables to raise an immediate ``NameError``
   which includes the name of the variable in its message
   when :meth:`~.Template.render` is called -- ``UNDEFINED`` is not used.
+
+  .. versionadded:: 0.3.6
+
 * **Why not just return None?** Using ``UNDEFINED``, or
   raising a ``NameError`` is more
   explicit and allows differentiation between a value of ``None``
@@ -196,7 +198,7 @@ The Loop Context
 ================
 
 Within ``% for`` blocks, the :ref:`reserved name<reserved_names>` ``loop``
-is available.  As a new feature of Mako 0.7, ``loop`` tracks the progress of
+is available.  ``loop`` tracks the progress of
 the ``for`` loop and makes it easy to use the iteration state to control
 template behavior:
 
@@ -208,6 +210,8 @@ template behavior:
     % endfor
     </ul>
 
+.. versionadded:: 0.7
+
 Iterations
 ----------
 
@@ -324,9 +328,12 @@ loop to make a checkered table:
 Migrating Legacy Templates that Use the Word "loop"
 ---------------------------------------------------
 
-The ``loop`` name is now :ref:`reserved <reserved_names>` in Mako, which means a template that refers to a
-variable named ``loop`` won't function correctly when used in Mako 0.7.  To ease
-the transition for such systems, the feature can be disabled across the board for
+.. versionchanged:: 0.7
+   The ``loop`` name is now :ref:`reserved <reserved_names>` in Mako,
+   which means a template that refers to a variable named ``loop``
+   won't function correctly when used in Mako 0.7.
+
+To ease the transition for such systems, the feature can be disabled across the board for
 all templates, then re-enabled on a per-template basis for those templates which wish
 to make use of the new system.
 
@@ -413,9 +420,12 @@ Reserved Names
 --------------
 
 Mako has a few names that are considered to be "reserved" and can't be used
-as variable names.  As of 0.7, Mako raises an error if these words are found
-passed to the template as context arguments, whereas in previous versions they'd be silently
-ignored or lead to other error messages.
+as variable names.
+
+.. versionchanged:: 0.7
+   Mako raises an error if these words are found passed to the template
+   as context arguments, whereas in previous versions they'd be silently
+   ignored or lead to other error messages.
 
 * ``context`` - see :ref:`context`.
 * ``UNDEFINED`` - see :ref:`context_vars`.
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index bf67641..3d9e1c5 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -306,7 +306,7 @@ div.note, div.warning, p.deprecated, div.topic  {
 }
 
 
-div.admonition, div.topic, p.deprecated {
+div.admonition, div.topic, p.deprecated, p.versionadded, p.versionchanged {
     border:1px solid #CCCCCC;
     padding:5px 10px;
     font-size:.9em;
@@ -337,6 +337,12 @@ dl.exception > dt
     padding: 0px 10px;
 }
 
+p.versionadded span.versionmodified,
+p.versionchanged span.versionmodified,
+p.deprecated span.versionmodified {
+    background-color: #F0F0F0;
+    font-style: italic;
+}
 
 dt:target, span.highlight {
     background-color:#FBE54E;
diff --git a/doc/build/syntax.rst b/doc/build/syntax.rst
index 70727d6..389147e 100644
--- a/doc/build/syntax.rst
+++ b/doc/build/syntax.rst
@@ -112,9 +112,8 @@ line, by escaping it as in ``%%``:
 The Loop Context
 ----------------
 
-Mako 0.7 includes a new feature called the **loop context** which
-provides additional information about a loop while inside of a ``% for``
-structure:
+The **loop context** provides additional information about a loop
+while inside of a ``% for`` structure:
 
 .. sourcecode:: mako
 
@@ -126,6 +125,8 @@ structure:
 
 See :ref:`loop_context` for more information on this feature.
 
+.. versionadded:: 0.7
+
 Comments
 ========
 
@@ -321,8 +322,8 @@ full deal on what ``%def`` can do in :ref:`defs_toplevel`.
 ``<%block>``
 ------------
 
-``%block`` is a tag that's new as of Mako 0.4.1. It's close to
-a ``%def``, except executes itself immediately in its base-most scope,
+``%block`` is a tag that is close to a ``%def``,
+except executes itself immediately in its base-most scope,
 and can also be anonymous (i.e. with no name):
 
 .. sourcecode:: mako
@@ -347,6 +348,8 @@ to do inheritance:
 
 Blocks are introduced in :ref:`blocks` and further described in :ref:`inheritance_toplevel`.
 
+.. versionadded:: 0.4.1
+
 ``<%namespace>``
 ----------------
 
@@ -387,7 +390,7 @@ Check it out in :ref:`inheritance_toplevel`.
 ``<%``\ nsname\ ``:``\ defname\ ``>``
 -------------------------------------
 
-As of Mako 0.2.3, any user-defined "tag" can be created against
+Any user-defined "tag" can be created against
 a namespace by using a tag with a name of the form
 ``<%<namespacename>:<defname>>``. The closed and open formats of such a
 tag are equivalent to an inline expression and the ``<%call>``
@@ -402,6 +405,8 @@ tag, respectively.
 To create custom tags which accept a body, see
 :ref:`defs_with_content`.
 
+.. versionadded:: 0.2.3
+
 ``<%call>``
 -----------
 
diff --git a/doc/build/unicode.rst b/doc/build/unicode.rst
index 61ca35c..a8bdcc7 100644
--- a/doc/build/unicode.rst
+++ b/doc/build/unicode.rst
@@ -323,12 +323,14 @@ mode you **cannot** safely call :meth:`~.Template.render_unicode` -- you'll get
 unicode/decode errors.
 
 The ``h`` filter (HTML escape) uses a less performant pure Python
-escape function in non-unicode mode (note that in versions prior
-to 0.3.4, it used ``cgi.escape()``, which has been replaced with a
-function that also escapes single quotes). This because
+escape function in non-unicode mode. This because
 MarkupSafe only supports Python unicode objects for non-ASCII
 strings.
 
+.. versionchanged:: 0.3.4
+   In prior versions, it used ``cgi.escape()``, which has been replaced
+   with a function that also escapes single quotes.
+
 Rules for using ``disable_unicode=True``
 ----------------------------------------
 
diff --git a/mako/cache.py b/mako/cache.py
index c831080..09b04fb 100644
--- a/mako/cache.py
+++ b/mako/cache.py
@@ -16,13 +16,14 @@ class Cache(object):
     """Represents a data content cache made available to the module
     space of a specific :class:`.Template` object.
 
-    As of Mako 0.6, :class:`.Cache` by itself is mostly a
-    container for a :class:`.CacheImpl` object, which implements
-    a fixed API to provide caching services; specific subclasses exist to
-    implement different
-    caching strategies.   Mako includes a backend that works with
-    the Beaker caching system.   Beaker itself then supports
-    a number of backends (i.e. file, memory, memcached, etc.)
+    .. versionadded:: 0.6
+       :class:`.Cache` by itself is mostly a
+       container for a :class:`.CacheImpl` object, which implements
+       a fixed API to provide caching services; specific subclasses exist to
+       implement different
+       caching strategies.   Mako includes a backend that works with
+       the Beaker caching system.   Beaker itself then supports
+       a number of backends (i.e. file, memory, memcached, etc.)
 
     The construction of a :class:`.Cache` is part of the mechanics
     of a :class:`.Template`, and programmatic access to this
diff --git a/mako/template.py b/mako/template.py
index 9d77f3b..7ab6a46 100644
--- a/mako/template.py
+++ b/mako/template.py
@@ -44,15 +44,20 @@ class Template(object):
      the `StringIO` or `cStringIO` buffer will be used instead of the
      default "fast" buffer.   This allows raw bytestrings in the
      output stream, such as in expressions, to pass straight
-     through to the buffer.   New in 0.4 to provide the same
-     behavior as that of the previous series.  This flag is forced
+     through to the buffer.  This flag is forced
      to ``True`` if ``disable_unicode`` is also configured.
 
+     .. versionadded:: 0.4
+        Added to provide the same behavior as that of the previous series.
+
     :param cache_args: Dictionary of cache configuration arguments that
      will be passed to the :class:`.CacheImpl`.   See :ref:`caching_toplevel`.
 
-    :param cache_dir: Deprecated; use the ``'dir'`` argument in the
-     ``cache_args`` dictionary.  See :ref:`caching_toplevel`.
+    :param cache_dir:
+
+     .. deprecated:: 0.6
+        Use the ``'dir'`` argument in the ``cache_args`` dictionary.
+        See :ref:`caching_toplevel`.
 
     :param cache_enabled: Boolean flag which enables caching of this
      template.  See :ref:`caching_toplevel`.
@@ -60,11 +65,17 @@ class Template(object):
     :param cache_impl: String name of a :class:`.CacheImpl` caching
      implementation to use.   Defaults to ``'beaker'``.
 
-    :param cache_type: Deprecated; use the ``'type'`` argument in the
-     ``cache_args`` dictionary.  See :ref:`caching_toplevel`.
+    :param cache_type:
+
+     .. deprecated:: 0.6
+        Use the ``'type'`` argument in the ``cache_args`` dictionary.
+        See :ref:`caching_toplevel`.
 
-    :param cache_url: Deprecated; use the ``'url'`` argument in the
-     ``cache_args`` dictionary.  See :ref:`caching_toplevel`.
+    :param cache_url:
+
+     .. deprecated:: 0.6
+        Use the ``'url'`` argument in the ``cache_args`` dictionary.
+        See :ref:`caching_toplevel`.
 
     :param default_filters: List of string filter names that will
      be applied to all expressions.  See :ref:`filtering_default_filters`.
@@ -165,7 +176,9 @@ class Template(object):
      ``UNDEFINED`` for any undeclared variables not located in
      the :class:`.Context` with an immediate raise of
      ``NameError``. The advantage is immediate reporting of
-     missing variables which include the name. New in 0.3.6.
+     missing variables which include the name.
+
+     .. versionadded:: 0.3.6
 
     :param uri: string URI or other identifier for this template.
      If not provided, the ``uri`` is generated from the filesystem