Initial documentation of IRenderables.

master/docs/manual/customization.rst

@@ -510,29 +510,30 @@ repos and workdir, this will work.
 Advanced Property Interpolation
 -------------------------------
 
-TODO
-
-If the simple string substitutions described in :ref:`Properties` are not
-sufficent, more complex substitutions can be achieved with
-:class:`Interpolate` and Python functions.  This only works with
-dictionary-style interpolation.
-
-The function should take one argument - a properties object, described below -
-and should return a string.  Pass the function as a keyword argument to
-:class:`WithProperties`, and use the name of that keyword argument in the
-interpolating string. For example::
-
-    def determine_foo(props):
-        if props.hasProperty('bar'):
-            return props['bar']
-        elif props.hasProperty('baz'):
-            return props['baz']
-        return 'qux'
-    WithProperties('%(foo)s', foo=determine_foo)
+If the simple string substitutions described in :ref:`Properties` are not sufficent, more complex substitutions can be achieved by writting custom renderers.
+
+Define a class with method `getRenderingFor`.
+The method should take one argument - a properties object, described below - and should return a string.
+Pass instances of the class anywhere other renderables are accepted.
+For example::
+
+    class DetermineFoo(object):
+        implements(IRenderable)
+        def getRenderingFor(self, props)
+            if props.hasProperty('bar'):
+                return props['bar']
+            elif props.hasProperty('baz'):
+                return props['baz']
+            return 'qux'
+    ShellCommand(command=['echo', DetermineFoo()])
 
 or, more practically, ::
 
-    WithProperties('%(now)s', now=lambda _: time.clock())
+    class Now(object):
+        implements(IRenderable)
+        def getRenderingFor(self, props)
+            return time.clock()
+    ShellCommand(command=['make', Interpolate('TIME=%(kw:now)', now=Now())])
 
 Properties Objects
 ~~~~~~~~~~~~~~~~~~