Sub-templates in reStructuredText

You can use
reStructuredText
or rst in a multitude of ways.
Typical usage from within a templating system is likely
that you want to build a web page that contains pieces of content
in rst i.e. you want to automatically process rst sub-templates
from within a containing HTML template —
to achieve this, all you need is to specify an appropriate
rst filter on the sub-template.
Let’s see this with an example (coming straight from the unit
test data included in the Evoque distribution).

The templates

First, just a sample rst source template file
(incidentally, this is the long description of the
QuickWikiEvoque package on PyPI ):

reStructuredText.rst

QuickWikiEvoque tutorial application - 
for Pylons_ >=${PYLONS_VER}, Evoque_ 0.4, SQLALchemy_ 0.5

An updated version of the original QuickWiki tutorial application
for Pylons, to work with:

- Pylons >=${PYLONS_VER} (instead of 0.9.6), 
- Evoque (instead of Mako) and 
- SQLAlchemy 0.5 (instead of 0.4).

Please follow the original explanatory text at 
http://wiki.pylonshq.com/display/pylonsdocs/QuickWiki+Tutorial 
for step by step explanations, with the obvious replacements for 
the different versions as indicated above, and for the actual code 
just look at the source code in the distribution.

.. _Pylons: http://www.pylonshq.com/
.. _Evoque: http://evoque.gizmojo.org/
.. _SQLAlchemy: http://www.sqlalchemy.org/

And a sample HTML containing template:

rst_container.html

<div class="rst">
    $evoque{reStructuredText.rst, filters=[rst]}
</div>

Output

We must define an appropriate rst-to-HTML filter
and the easiest way is to set it as a global on the domain.
We then render the containing template:

from docutils.core import publish_parts
def rst(rst):
    return publish_parts(rst, writer_name="html")["fragment"]
domain.set_on_globals("rst", rst)
domain.get_template("rst_container.html").evoque(PYLONS_VER="0.9.7")

That will produce the following output (rendered as the content of the box below):

Using a collection

When we have multiple rst templates we probably do not want to bother with
having to always set the same filters or other options each time we
evoque one of them.
For this case we can choose to define a collection to contain our rst
templates and set the filters or other options we want as defaults on the
collection. We may set this up simply with something like (here we just
specify only one default, filters, but collections support
several others):

domain.set_collection("rst", "/docs/templates/rst", filters=[rst])

Thus, any rst template we evoque from this collection
will inherit any defaults on the collection.
The price to be paid for this is that to address a template
from another collection, we need to explicitly specify
the target collection. So, for the example above, the outer
rst_container.html HTML template (that in this scenario
is not within the rst collection) would become:

<div class="rst">
    $evoque{reStructuredText.rst, collection="rst"}
</div>