evoque

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>