1 files changed, 60 insertions, 3 deletions
diff --git a/docs/api/template.rst b/docs/api/template.rst
index 64e25a37c..8cf63c91b 100644
--- a/docs/api/template.rst
+++ b/docs/api/template.rst
@@ -1,9 +1,56 @@
 .. _template_module:
 
-:mod:`repoze.bfg.template`
---------------------------
+:mod:`repoze.bfg` Built-in Templating Facilties
+===============================================
 
-.. automodule:: repoze.bfg.template
+Three templating facilities are provided by :mod:`repoze.bfg` "out of
+the box": :term:`ZPT` -style, :term:`Genshi` -style, and :term:`XSLT`
+templating.
+
+ZPT-style and Genshi-style templates are in :mod:`repoze.bfg` are
+supported by the :term:`Chameleon` (nee :term:`z3c.pt`) templating
+engine, which contains alternate implementations of both the ZPT and
+Genshi language specifications.
+
+XSLT templating is supported by the use of :term:`lxml`.
+
+Below is API documentation for each of those facilities.  Each
+facility is similar to the other, but to use a particular facility,
+you must import the API function from a specific module.  For
+instance, to render a ZPT-style template to a response, you would
+import the ``render_template_to_response`` function from
+``repoze.bfg.chameleon_zpt`` while you would import
+``render_template_to_response`` from ``repoze.bfg.chameleon_genshi``
+in order to render a Genshi-style template to a response.  While these
+functions have the same name, each will only operate on template files
+that match the style in which the template file itself is written.  If
+you need to import API functions from two templating facilities within
+the same module, use the ``as`` feature of the Python import
+statement, e.g.:
+
+.. code-block:: python
+
+  from repoze.chameleon_zpt import render_template as zpt_render
+  from repoze.chameleon_genshi import render_template as genshi_render
+
+:mod:`repoze.bfg.chameleon_zpt`
+-------------------------------
+
+.. automodule:: repoze.bfg.chameleon_zpt
+
+  .. autofunction:: get_template
+
+  .. autofunction:: render_template
+
+  .. autofunction:: render_template_to_response
+
+.. note:: For backwards compatibility purposes, these functions may
+          also be imported from ``repoze.bfg.template``.
+
+:mod:`repoze.bfg.chameleon_genshi`
+----------------------------------
+
+.. automodule:: repoze.bfg.chameleon_genshi
 
   .. autofunction:: get_template
 
@@ -11,7 +58,17 @@
 
   .. autofunction:: render_template_to_response
 
+:mod:`repoze.bfg.xslt`
+----------------------
+
+.. automodule:: repoze.bfg.xslt
+
+  .. autofunction:: get_transform
+
   .. autofunction:: render_transform
 
   .. autofunction:: render_transform_to_response
 
+.. note:: For backwards compatibility purposes, these functions may
+          also be imported from ``repoze.bfg.template``.
+