Uniformise documentation sections titles style:

use caps on words, undescoring characters match exact title length,
only one empty line separates title with preceding section content.

10 files changed, 67 insertions, 70 deletions

diff --git a/doc/build/caching.rst b/doc/build/caching.rst
index 31bbba4..a87f525 100644
--- a/doc/build/caching.rst
+++ b/doc/build/caching.rst
@@ -1,8 +1,8 @@
 .. _caching_toplevel:
 
-========
+=======
 Caching
-========
+=======
 
 Any template or component can be cached using the ``cache``
 argument to the ``<%page>``, ``<%def>`` or ``<%block>`` directives:
@@ -41,8 +41,8 @@ its options can be used with the ``<%def>`` tag as well:
         other text
     </%block>
 
-Cache arguments
-================
+Cache Arguments
+===============
 
 Mako has two cache arguments available on tags that are
 available in all cases.   The rest of the arguments
@@ -126,7 +126,7 @@ The actual arguments understood are determined by the backend.
 .. _beaker_backend:
 
 Using the Beaker Cache Backend
--------------------------------
+------------------------------
 
 When using Beaker, new implementations will want to make usage
 of **cache regions** so that cache configurations can be maintained
@@ -221,7 +221,7 @@ without the ``cache_`` prefix in the ``cache_args`` dictionary:
 .. _dogpile.cache_backend:
 
 Using the dogpile.cache Backend
---------------------------------
+-------------------------------
 
 `dogpile.cache`_ is a new replacement for Beaker.   It provides
 a modernized, slimmed down interface and is generally easier to use
@@ -278,7 +278,7 @@ later time.
 .. _cache_plugins:
 
 Cache Plugins
-==============
+=============
 
 The mechanism used by caching can be plugged in
 using a :class:`.CacheImpl` subclass.    This class implements
@@ -331,7 +331,7 @@ Enabling the above plugin in a template would look like:
                     file="mytemplate.html",
                     cache_impl='simple')
 
-Guidelines for writing cache plugins
+Guidelines for Writing Cache Plugins
 ------------------------------------
 
 * The :class:`.CacheImpl` is created on a per-:class:`.Template` basis.  The
@@ -370,7 +370,7 @@ Guidelines for writing cache plugins
   conflicts with generated modules don't occur.
 
 API Reference
-==============
+=============
 
 .. autoclass:: mako.cache.Cache
     :members:
diff --git a/doc/build/defs.rst b/doc/build/defs.rst
index 8916c39..1d55df8 100644
--- a/doc/build/defs.rst
+++ b/doc/build/defs.rst
@@ -73,7 +73,7 @@ value). This is in contrast to using context-level variables,
 which evaluate to ``UNDEFINED`` if you reference a name that
 does not exist.
 
-Calling defs from Other Files
+Calling Defs from Other Files
 -----------------------------
 
 Top level ``<%def>``\ s are **exported** by your template's
@@ -117,7 +117,7 @@ which is a central Mako concept that has its own chapter in
 these docs. For more detail and examples, see
 :ref:`namespaces_toplevel`.
 
-Calling defs programmatically
+Calling Defs Programmatically
 -----------------------------
 
 You can call defs programmatically from any :class:`.Template` object
@@ -201,7 +201,7 @@ in the expression that tries to render it.
 
 .. _defs_with_content:
 
-Calling a def with embedded content and/or other defs
+Calling a Def with Embedded Content and/or Other Defs
 -----------------------------------------------------
 
 A flip-side to def within def is a def call with content. This
@@ -518,7 +518,6 @@ rendering body, so have access to local variable scope:
         <%block>i is ${i}</%block>
     % endfor
 
-
 Using Named Blocks
 ------------------
 
@@ -576,8 +575,8 @@ To keep things sane, named blocks have restrictions that defs do not:
 * A named ``<%block>`` cannot be defined within a ``<%def>``, or inside the body of a "call", i.e.
   ``<%call>`` or ``<%namespacename:defname>`` tag.  Anonymous blocks can, however.
 
-Using page arguments in named blocks
--------------------------------------
+Using Page Arguments in Named Blocks
+------------------------------------
 
 A named block is very much like a top level def. It has a similar
 restriction to these types of defs in that arguments passed to the
diff --git a/doc/build/filtering.rst b/doc/build/filtering.rst
index cb8bb92..ba45d1a 100644
--- a/doc/build/filtering.rst
+++ b/doc/build/filtering.rst
@@ -5,7 +5,7 @@ Filtering and Buffering
 =======================
 
 Expression Filtering
-=====================
+====================
 
 As described in the chapter :ref:`syntax_toplevel`, the "``|``" operator can be
 applied to a "``${}``" expression to apply escape filters to the
@@ -147,8 +147,8 @@ The above will generate templates something like this:
     def render_body(context):
         context.write(myfilter(unicode("some text")))
 
-Turning off Filtering with the ``n`` filter
---------------------------------------------
+Turning off Filtering with the ``n`` Filter
+-------------------------------------------
 
 In all cases the special ``n`` filter, used locally within an
 expression, will **disable** all filters declared in the
@@ -167,7 +167,7 @@ will render ``myexpression`` with no filtering of any kind, and:
 will render ``myexpression`` using the ``trim`` filter only.
 
 Filtering Defs and Blocks
-==========================
+=========================
 
 The ``%def`` and ``%block`` tags have an argument called ``filter`` which will apply the
 given list of filter functions to the output of the ``%def``:
@@ -182,7 +182,7 @@ When the ``filter`` attribute is applied to a def as above, the def
 is automatically **buffered** as well. This is described next.
 
 Buffering
-==========
+=========
 
 One of Mako's central design goals is speed. To this end, all of
 the textual content within a template and its various callables
@@ -278,7 +278,7 @@ The above call is equivalent to the unbuffered call:
     ${somedef(17, 'hi', use_paging=True)}
 
 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``
diff --git a/doc/build/index.rst b/doc/build/index.rst
index 01d0f17..a81d5ba 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -14,7 +14,7 @@ Table of Contents
     unicode
     caching
 
-Indices and tables
+Indices and Tables
 ------------------
 
 * :ref:`genindex`
diff --git a/doc/build/inheritance.rst b/doc/build/inheritance.rst
index 96072d5..b4871bf 100644
--- a/doc/build/inheritance.rst
+++ b/doc/build/inheritance.rst
@@ -168,7 +168,7 @@ Note when we overrode ``header``, we added an extra call ``${parent.header()}``
 the parent's ``header`` block in addition to our own.  That's described in more detail below,
 in :ref:`parent_namespace`.
 
-Rendering a named block multiple times
+Rendering a Named Block Multiple Times
 ======================================
 
 Recall from the section :ref:`blocks` that a named block is just like a ``<%def>``,
@@ -192,8 +192,8 @@ a section that is used more than once, such as the title of a page:
 Where above an inheriting template can define ``<%block name="title">`` just once, and it will be
 used in the base template both in the ``<title>`` section as well as the ``<h2>``.
 
-But what about defs?
-=====================
+But what about Defs?
+====================
 
 The previous example used the ``<%block>`` tag to produce areas of content
 to be overridden.  Before Mako 0.4.1, there wasn't any such tag -- instead
@@ -317,8 +317,8 @@ in order to achieve this it *adds* the restriction that all block names in a sin
 to be globally unique within the template, and additionally that a ``<%block>`` can't be defined
 inside of a ``<%def>``. It's a more restricted tag suited towards a more specific use case than ``<%def>``.
 
-Using the ``next`` namespace to produce content wrapping
-=========================================================
+Using the ``next`` Namespace to Produce Content Wrapping
+========================================================
 
 Sometimes you have an inheritance chain that spans more than two
 templates. Or maybe you don't, but you'd like to build your
@@ -427,8 +427,8 @@ Without the ``next`` namespace, only the main body of
 
 .. _parent_namespace:
 
-Using the ``parent`` namespace to augment defs
-===============================================
+Using the ``parent`` Namespace to Augment Defs
+==============================================
 
 Lets now look at the other inheritance-specific namespace, the
 opposite of ``next`` called ``parent``. ``parent`` is the
diff --git a/doc/build/namespaces.rst b/doc/build/namespaces.rst
index 070c9dd..95e8f7a 100644
--- a/doc/build/namespaces.rst
+++ b/doc/build/namespaces.rst
@@ -72,7 +72,7 @@ context variables, the ``context`` must be named explicitly:
     <%namespace name="dyn" file="${context['namespace_name']}"/>
 
 Ways to Call Namespaces
-========================
+=======================
 
 There are essentially four ways to call a function from a
 namespace.
@@ -126,7 +126,7 @@ the caller, see :ref:`defs_with_content`.
 .. _namespaces_python_modules:
 
 Namespaces from Regular Python Modules
-========================================
+======================================
 
 Namespaces can also import regular Python functions from
 modules. These callables need to take at least one argument,
@@ -184,8 +184,8 @@ which accepts the "context" as its first argument:
         return "<div>%s</div>" % \
                 capture(context, context['caller'].body, x="foo", y="bar")
 
-Declaring defs in namespaces
-=============================
+Declaring Defs in Namespaces
+============================
 
 The ``<%namespace>`` tag supports the definition of ``<%def>``\ s
 directly inside the tag. These defs become part of the namespace
@@ -206,8 +206,8 @@ pulled in from a remote template or module:
 
 .. _namespaces_body:
 
-The ``body()`` method
-=======================
+The ``body()`` Method
+=====================
 
 Every namespace that is generated from a template contains a
 method called ``body()``. This method corresponds to the main
@@ -261,7 +261,7 @@ this, as well as the meanings of the names ``self`` and
 .. _namespaces_builtin:
 
 Built-in Namespaces
-====================
+===================
 
 The namespace is so great that Mako gives your template one (or
 two) for free. The names of these namespaces are ``local`` and
@@ -287,7 +287,7 @@ can be particularly useful.
 .. _namespace_self:
 
 ``self``
----------
+--------
 
 The ``self`` namespace, in the case of a template that does not
 use inheritance, is synonymous with ``local``. If inheritance is
@@ -298,7 +298,7 @@ overridden at various points in an inheritance chain. See
 :ref:`inheritance_toplevel`.
 
 Inheritable Namespaces
-========================
+======================
 
 The ``<%namespace>`` tag includes an optional attribute
 ``inheritable="True"``, which will cause the namespace to be
@@ -329,7 +329,7 @@ use the explicit namespace name off of ``self``, followed by the
 desired function name. But more on this in a future release.
 
 API Reference
-==============
+=============
 
 .. autoclass:: mako.runtime.Namespace
     :show-inheritance:
diff --git a/doc/build/runtime.rst b/doc/build/runtime.rst
index d42a922..980b8a4 100644
--- a/doc/build/runtime.rst
+++ b/doc/build/runtime.rst
@@ -1,8 +1,8 @@
 .. _runtime_toplevel:
 
-=============================
+============================
 The Mako Runtime Environment
-=============================
+============================
 
 This section describes a little bit about the objects and
 built-in functions that are available in templates.
@@ -55,7 +55,7 @@ buffer.
 .. _context_vars:
 
 Context Variables
-------------------
+-----------------
 
 When your template is compiled into a Python module, the body
 content is enclosed within a Python function called
@@ -159,7 +159,7 @@ are all stored in unique :class:`.Context` instances).
   be explicit.
 
 Context Methods and Accessors
-------------------------------
+-----------------------------
 
 Significant members of :class:`.Context` include:
 
@@ -208,7 +208,6 @@ template behavior:
     % endfor
     </ul>
 
-
 Iterations
 ----------
 
@@ -256,8 +255,7 @@ Both approaches produce output like the following:
           <li class="even">eggs</li>
         </ul>
 
-
-Parent loops
+Parent Loops
 ------------
 
 Loop contexts can also be transparently nested, and the Mako runtime will do
@@ -362,7 +360,7 @@ the ``<%page>`` tag doesn't override it.  New templates that want to use the ``l
 can then set up ``<%page enable_loop="True"/>`` to use the new feature without affecting
 old templates.
 
-All the built-in names
+All the Built-in Names
 ======================
 
 A one-stop shop for all the names Mako defines. Most of these
@@ -411,7 +409,7 @@ to the context and can't be substituted -- see the section :ref:`reserved_names`
 
 .. _reserved_names:
 
-Reserved names
+Reserved Names
 --------------
 
 Mako has a few names that are considered to be "reserved" and can't be used
@@ -425,7 +423,7 @@ ignored or lead to other error messages.
   via the ``enable_loop=False`` argument; see :ref:`migrating_loop`.
 
 API Reference
-==============
+=============
 
 .. autoclass:: mako.runtime.Context
     :show-inheritance:
diff --git a/doc/build/syntax.rst b/doc/build/syntax.rst
index 875085e..70727d6 100644
--- a/doc/build/syntax.rst
+++ b/doc/build/syntax.rst
@@ -15,7 +15,7 @@ you can leverage the full power of Python in almost every aspect
 of a Mako template.
 
 Expression Substitution
-========================
+=======================
 
 The simplest expression is just a variable substitution. The
 syntax for this is the ``${}`` construct, which is inspired by
@@ -147,7 +147,7 @@ A multiline version exists using ``<%doc> ...text... </%doc>``:
     </%doc>
 
 Newline Filters
-================
+===============
 
 The backslash ("``\``") character, placed at the end of any
 line, will consume the newline character before continuing to
@@ -188,7 +188,7 @@ Mako's compiler will adjust the block of Python to be consistent
 with the surrounding generated Python code.
 
 Module-level Blocks
-====================
+===================
 
 A variant on ``<% %>`` is the module-level code block, denoted
 by ``<%! %>``. Code within these tags is executed at the module
@@ -274,7 +274,7 @@ want. The details of what ``<%page>`` is used for are described
 further in :ref:`namespaces_body` as well as :ref:`caching_toplevel`.
 
 ``<%include>``
----------------
+--------------
 
 A tag that is familiar from other template languages, ``%include``
 is a regular joe that just accepts a file argument and calls in
@@ -319,7 +319,7 @@ arguments to other def calls (not as hard as it sounds). Get the
 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,
@@ -348,7 +348,7 @@ to do inheritance:
 Blocks are introduced in :ref:`blocks` and further described in :ref:`inheritance_toplevel`.
 
 ``<%namespace>``
------------------
+----------------
 
 ``%namespace`` is Mako's equivalent of Python's ``import``
 statement. It allows access to all the rendering functions and
@@ -385,7 +385,7 @@ inheritance, content wrapping, and polymorphic method calls.
 Check it out in :ref:`inheritance_toplevel`.
 
 ``<%``\ nsname\ ``:``\ defname\ ``>``
----------------------------------------------
+-------------------------------------
 
 As of Mako 0.2.3, any user-defined "tag" can be created against
 a namespace by using a tag with a name of the form
@@ -438,7 +438,7 @@ Mako:
         <%def name="x()">${x}</%def>
     <%/text>
 
-Returning early from a template
+Returning Early from a Template
 ===============================
 
 Sometimes you want to stop processing a template or ``<%def>``
diff --git a/doc/build/unicode.rst b/doc/build/unicode.rst
index e0537c8..61ca35c 100644
--- a/doc/build/unicode.rst
+++ b/doc/build/unicode.rst
@@ -87,7 +87,7 @@ encoding <defining_output_encoding>` (still required in Python 3).
 .. _set_template_file_encoding:
 
 Specifying the Encoding of a Template File
-===========================================
+==========================================
 
 This is the most basic encoding-related setting, and it is
 equivalent to Python's "magic encoding comment", as described in
@@ -133,7 +133,7 @@ encoding comment, which takes precedence.
 .. _handling_non_ascii_expressions:
 
 Handling Expressions
-=====================
+====================
 
 The next area that encoding comes into play is in expression
 constructs. By default, Mako's treatment of an expression like
@@ -210,7 +210,7 @@ in :ref:`filtering_default_filters`.
 .. _defining_output_encoding:
 
 Defining Output Encoding
-=========================
+========================
 
 Now that we have a template which produces a pure unicode output
 stream, all the hard work is done. We can take the output and do
@@ -250,7 +250,7 @@ you can encode yourself by saying:
     print mytemplate.render_unicode().encode('utf-8', 'replace')
 
 Buffer Selection
------------------
+----------------
 
 Mako does play some games with the style of buffering used
 internally, to maximize performance. Since the buffer is by far
@@ -269,8 +269,8 @@ a list and uses ``u''.join(elements)`` to produce the final output
 
 .. _unicode_disabled:
 
-Saying to Heck with it: Disabling the usage of Unicode entirely
-================================================================
+Saying to Heck with It: Disabling the Usage of Unicode Entirely
+===============================================================
 
 Some segments of Mako's userbase choose to make no usage of
 Unicode whatsoever, and instead would prefer the "pass through"
diff --git a/doc/build/usage.rst b/doc/build/usage.rst
index 0e50ddf..d6e5338 100644
--- a/doc/build/usage.rst
+++ b/doc/build/usage.rst
@@ -62,7 +62,7 @@ render with it, using the :meth:`~.Template.render_context` method:
     print buf.getvalue()
 
 Using File-Based Templates
-===========================
+==========================
 
 A :class:`.Template` can also load its template source code from a file,
 using the ``filename`` keyword argument:
@@ -177,7 +177,7 @@ clean out a certain percentage of templates using a least
 recently used scheme.
 
 Setting Filesystem Checks
---------------------------
+-------------------------
 
 Another important flag on :class:`.TemplateLookup` is
 ``filesystem_checks``. This defaults to ``True``, and says that each
@@ -192,7 +192,7 @@ the type of filesystem used).
 .. _usage_unicode:
 
 Using Unicode and Encoding
-===========================
+==========================
 
 Both :class:`.Template` and :class:`.TemplateLookup` accept ``output_encoding``
 and ``encoding_errors`` parameters which can be used to encode the
@@ -235,7 +235,7 @@ fully in :ref:`unicode_toplevel`.
 .. _handling_exceptions:
 
 Handling Exceptions
-====================
+===================
 
 Template exceptions can occur in two distinct places. One is
 when you **lookup, parse and compile** the template, the other
@@ -353,7 +353,7 @@ of files, and also displays errors using Mako's included
 exception-handling utilities.
 
 Pygments
----------
+--------
 
 A `Pygments <http://pygments.pocoo.org>`_-compatible syntax
 highlighting module is included under :mod:`mako.ext.pygmentplugin`.
@@ -363,7 +363,7 @@ also contains various `setuptools` entry points under the heading
 (see the ``setup.py`` file for all the entry points).
 
 Babel
-------
+-----
 
 Mako provides support for extracting `gettext` messages from
 templates via a `Babel`_ extractor
@@ -454,7 +454,7 @@ for more information.
 
 
 API Reference
-=================
+=============
 
 .. autoclass:: mako.template.Template
     :show-inheritance: