Anonymous committed ba6fea4

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.

Comments (0)

Files changed (10)


 .. _caching_toplevel:
 Any template or component can be cached using the ``cache``
 argument to the ``<%page>``, ``<%def>`` or ``<%block>`` directives:
         other text
-Cache arguments
+Cache Arguments
 Mako has two cache arguments available on tags that are
 available in all cases.   The rest of the arguments
 .. _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
 .. _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
 .. _cache_plugins:
 Cache Plugins
 The mechanism used by caching can be plugged in
 using a :class:`.CacheImpl` subclass.    This class implements
-Guidelines for writing cache plugins
+Guidelines for Writing Cache Plugins
 * The :class:`.CacheImpl` is created on a per-:class:`.Template` basis.  The
   conflicts with generated modules don't occur.
 API Reference
 .. autoclass:: mako.cache.Cache
 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
 these docs. For more detail and examples, see
-Calling defs programmatically
+Calling Defs Programmatically
 You can call defs programmatically from any :class:`.Template` object
 .. _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
         <%block>i is ${i}</%block>
     % endfor
 Using Named Blocks
 * 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


 Expression Filtering
 As described in the chapter :ref:`syntax_toplevel`, the "``|``" operator can be
 applied to a "``${}``" expression to apply escape filters to the
     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
 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``:
 is automatically **buffered** as well. This is described next.
 One of Mako's central design goals is speed. To this end, all of
 the textual content within a template and its various callables
     ${somedef(17, 'hi', use_paging=True)}
 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``
-Indices and tables
+Indices and Tables
 * :ref:`genindex`


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


     <%namespace name="dyn" file="${context['namespace_name']}"/>
 Ways to Call Namespaces
 There are essentially four ways to call a function from a
 .. _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,
         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
 .. _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
 .. _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
 .. _namespace_self:
 The ``self`` namespace, in the case of a template that does not
 use inheritance, is synonymous with ``local``. If inheritance is
 Inheritable Namespaces
 The ``<%namespace>`` tag includes an optional attribute
 ``inheritable="True"``, which will cause the namespace to be
 desired function name. But more on this in a future release.
 API Reference
 .. autoclass:: mako.runtime.Namespace


 .. _runtime_toplevel:
 The Mako Runtime Environment
 This section describes a little bit about the objects and
 built-in functions that are available in templates.
 .. _context_vars:
 Context Variables
 When your template is compiled into a Python module, the body
 content is enclosed within a Python function called
   be explicit.
 Context Methods and Accessors
 Significant members of :class:`.Context` include:
     % endfor
           <li class="even">eggs</li>
-Parent loops
+Parent Loops
 Loop contexts can also be transparently nested, and the Mako runtime will do
 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
 .. _reserved_names:
-Reserved names
+Reserved Names
 Mako has a few names that are considered to be "reserved" and can't be used
   via the ``enable_loop=False`` argument; see :ref:`migrating_loop`.
 API Reference
 .. autoclass:: mako.runtime.Context
 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
 Newline Filters
 The backslash ("``\``") character, placed at the end of any
 line, will consume the newline character before continuing to
 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
 further in :ref:`namespaces_body` as well as :ref:`caching_toplevel`.
 A tag that is familiar from other template languages, ``%include``
 is a regular joe that just accepts a file argument and calls in
 full deal on what ``%def`` can do in :ref:`defs_toplevel`.
 ``%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,
 Blocks are introduced in :ref:`blocks` and further described in :ref:`inheritance_toplevel`.
 ``%namespace`` is Mako's equivalent of Python's ``import``
 statement. It allows access to all the rendering functions and
 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
         <%def name="x()">${x}</%def>
-Returning early from a template
+Returning Early from a Template
 Sometimes you want to stop processing a template or ``<%def>``


 .. _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
 .. _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
 .. _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
     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
 .. _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"
     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:
 recently used scheme.
 Setting Filesystem Checks
 Another important flag on :class:`.TemplateLookup` is
 ``filesystem_checks``. This defaults to ``True``, and says that each
 .. _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
 .. _handling_exceptions:
 Handling Exceptions
 Template exceptions can occur in two distinct places. One is
 when you **lookup, parse and compile** the template, the other
 exception-handling utilities.
 A `Pygments <>`_-compatible syntax
 highlighting module is included under :mod:`mako.ext.pygmentplugin`.
 (see the ```` file for all the entry points).
 Mako provides support for extracting `gettext` messages from
 templates via a `Babel`_ extractor
 API Reference
 .. autoclass:: mako.template.Template