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.
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 @@ 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 @@ .. _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 @@ .. _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 @@ .. _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 @@ 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 @@ 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 @@ 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 @@ 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 @@ .. _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 @@ <%block>i is ${i}</%block> % endfor - Using Named Blocks ------------------ @@ -576,8 +575,8 @@ * 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 @@ ======================= 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 @@ 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`` 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 @@ 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 @@ ${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 @@ 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 @@ 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 @@ 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 @@ 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 @@ .. _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 @@ <%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 @@ .. _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 @@ 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 @@ .. _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 @@ .. _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 @@ .. _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 @@ :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 @@ 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 @@ .. _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 @@ be explicit. Context Methods and Accessors ------------------------------- +----------------------------- Significant members of :class:`.Context` include: @@ -208,7 +208,6 @@ % endfor </ul> - Iterations ---------- @@ -256,8 +255,7 @@ <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 @@ 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 @@ .. _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 @@ 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 @@ 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 @@ </%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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ <%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 @@ .. _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 @@ .. _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 @@ .. _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 @@ 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 @@ .. _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 @@ 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 @@ 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 @@ .. _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 @@ .. _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 @@ 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 @@ (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 @@ API Reference -================= +============= .. autoclass:: mako.template.Template :show-inheritance: