Commits

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)

doc/build/caching.rst

 .. _caching_toplevel:
 
-========
+=======
 Caching
-========
+=======
 
 Any template or component can be cached using the ``cache``
 argument to the ``<%page>``, ``<%def>`` or ``<%block>`` directives:
         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
 .. _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
                     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
   conflicts with generated modules don't occur.
 
 API Reference
-==============
+=============
 
 .. autoclass:: mako.cache.Cache
     :members:
 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
 :ref:`namespaces_toplevel`.
 
-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

doc/build/filtering.rst

 =======================
 
 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.
 
 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
     ${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``
     unicode
     caching
 
-Indices and tables
+Indices and Tables
 ------------------
 
 * :ref:`genindex`

doc/build/inheritance.rst

 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

doc/build/namespaces.rst

     <%namespace name="dyn" file="${context['namespace_name']}"/>
 
 Ways to Call Namespaces
-========================
+=======================
 
 There are essentially four ways to call a function from a
 namespace.
 .. _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:
 
 ``self``
----------
+--------
 
 The ``self`` namespace, in the case of a template that does not
 use inheritance, is synonymous with ``local``. If inheritance is
 :ref:`inheritance_toplevel`.
 
 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
     :show-inheritance:

doc/build/runtime.rst

 .. _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
     </ul>
 
-
 Iterations
 ----------
 
           <li class="even">eggs</li>
         </ul>
 
-
-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
     :show-inheritance:
 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
     </%doc>
 
 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`.
 
 ``<%include>``
----------------
+--------------
 
 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>``
--------------
+------------
 
 ``%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>``
------------------
+----------------
 
 ``%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>
     <%/text>
 
-Returning early from a template
+Returning Early from a Template
 ===============================
 
 Sometimes you want to stop processing a template or ``<%def>``

doc/build/unicode.rst

 .. _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.
 
 Pygments
----------
+--------
 
 A `Pygments <http://pygments.pocoo.org>`_-compatible syntax
 highlighting module is included under :mod:`mako.ext.pygmentplugin`.
 (see the ``setup.py`` file for all the entry points).
 
 Babel
-------
+-----
 
 Mako provides support for extracting `gettext` messages from
 templates via a `Babel`_ extractor
 
 
 API Reference
-=================
+=============
 
 .. autoclass:: mako.template.Template
     :show-inheritance: