Anonymous avatar Anonymous committed 9f381fa

Add paragraph-level version information markup from Sphinx
(``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::``),
update docs CSS to put those infos into boxes.

Comments (0)

Files changed (9)

doc/build/caching.rst

 * ``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>`_
 
 * ``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
 --------------------------------
 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,

doc/build/defs.rst

 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

doc/build/filtering.rst

 * ``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
 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

doc/build/runtime.rst

   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``
 ================
 
 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:
 
     % endfor
     </ul>
 
+.. versionadded:: 0.7
+
 Iterations
 ----------
 
 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.
 
 --------------
 
 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`.

doc/build/static/docs.css

 }
 
 
-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;
     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;

doc/build/syntax.rst

 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
 
 
 See :ref:`loop_context` for more information on this feature.
 
+.. versionadded:: 0.7
+
 Comments
 ========
 
 ``<%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
 
 Blocks are introduced in :ref:`blocks` and further described in :ref:`inheritance_toplevel`.
 
+.. versionadded:: 0.4.1
+
 ``<%namespace>``
 ----------------
 
 ``<%``\ 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>``
 To create custom tags which accept a body, see
 :ref:`defs_with_content`.
 
+.. versionadded:: 0.2.3
+
 ``<%call>``
 -----------
 

doc/build/unicode.rst

 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``
 ----------------------------------------
 
     """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
      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`.
     :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:
 
-    :param cache_url: Deprecated; use the ``'url'`` argument in the
-     ``cache_args`` dictionary.  See :ref:`caching_toplevel`.
+     .. deprecated:: 0.6
+        Use the ``'type'`` 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`.
      ``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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.