Using a single chapter for the API docs and a single chapter for the ZCML directives made it hard to read.

1 files changed, 53 insertions, 0 deletions

diff --git a/docs/zcml/renderer.rst b/docs/zcml/renderer.rst
new file mode 100644
index 000000000..1a3942ede
--- /dev/null
+++ b/docs/zcml/renderer.rst
@@ -0,0 +1,53 @@
+.. _renderer_directive:
+
+``renderer``
+------------
+
+The ``renderer`` ZCML directive can be used to override an existing
+existing :term:`renderer` or to add a new renderer.
+
+Attributes
+~~~~~~~~~~
+
+``factory``
+
+    A :term:`dotted Python name` referencing a callable object that
+    accepts a renderer name and returns a :term:`renderer` object.
+
+``name``
+
+   The renderer name, which is a string.
+
+Examples
+~~~~~~~~
+
+.. topic:: Registering a Non-Template Renderer
+
+   .. code-block:: xml
+      :linenos:
+
+      <renderer
+         factory="some.renderer"
+         name="mynewrenderer"
+         />
+
+.. topic:: Registering a Template Renderer
+
+   .. code-block:: xml
+      :linenos:
+
+      <renderer
+         factory="some.jinja2.renderer"
+         name=".jinja2"
+         />
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.add_renderer` method
+is equivalent to the ``renderer`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`adding_and_overriding_renderers`.