--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/pyams_template/doctests/README.rst	Tue Nov 26 10:09:41 2019 +0100
@@ -0,0 +1,103 @@
+======================
+pyams_template package
+======================
+
+This doctests are based on z3c.template doctests.
+
+First let's show how to produce content from a view:
+
+    >>> from pyramid.testing import setUp, tearDown
+    >>> config = setUp()
+
+    >>> import os, tempfile
+    >>> temp_dir = tempfile.mkdtemp()
+
+    >>> content_template = os.path.join(temp_dir, 'content-template.pt')
+    >>> with open(content_template, 'w') as file:
+    ...     _ = file.write('<div>Base template content</div>')
+
+We can now register a view class implementing an interface:
+
+    >>> from zope.interface import implementer, Interface
+    >>> from pyams_template.interfaces import IContentTemplate, IPageTemplate
+
+    >>> class IMyView(Interface):
+    ...     """View marker interface"""
+
+    >>> @implementer(IMyView)
+    ... class MyView:
+    ...     template = None
+    ...     def __init__(self, context, request):
+    ...         self.context = context
+    ...         self.request = request
+    ...     def __call__(self):
+    ...         if self.template is None:
+    ...             template = config.registry.getMultiAdapter((self, self.request),
+    ...                                                        IContentTemplate)
+    ...             return template()
+    ...         return self.template()
+
+Let's now call the view and check the output:
+
+    >>> from pyramid.testing import DummyRequest
+    >>> root = object()
+    >>> request = DummyRequest()
+    >>> view = MyView(root, request)
+
+Since the template is not yet registered, rendering may fail:
+
+    >>> view()
+    Traceback (most recent call last):
+    ...
+    zope.interface.interfaces.ComponentLookupError: ...
+
+So let's now register the template; this is commonly done using "template_config" decorator, or
+using ZCML:
+
+    >>> from pyams_template.template import TemplateFactory
+    >>> factory = TemplateFactory(content_template, 'text/html')
+    >>> factory
+    <pyams_template.template.TemplateFactory object at ...>
+
+    >>> from pyramid.interfaces import IRequest
+    >>> config.registry.registerAdapter(factory, (Interface, IRequest), IContentTemplate)
+    >>> config.registry.getMultiAdapter((view, request), IPageTemplate)
+    <PyramidPageTemplateFile .../content-template.pt>
+
+    >>> print(view())
+    <div>Base template content</div>
+
+Now we can register another template for this view:
+
+    >>> my_template = os.path.join(temp_dir, 'my-template.pt')
+    >>> with open(my_template, 'w') as file:
+    ...     _ = file.write('<div>This is my template</div>')
+    >>> factory = TemplateFactory(my_template, 'text/html')
+    >>> config.registry.registerAdapter(factory, (IMyView, IRequest), IContentTemplate)
+    >>> print(view())
+    <div>This is my template</div>
+
+It's generally easier to use a decorator to register templates:
+
+    >>> from pyramid.view import view_config
+    >>> from pyams_template.template import template_config
+
+    >>> my_other_template = os.path.join(temp_dir, 'my-other-template.pt')
+    >>> with open(my_other_template, 'w') as file:
+    ...     _ = file.write('<div>This is my template for view 2</div>')
+
+    >>> @template_config(template=my_other_template)
+    ... class MyView2(MyView):
+    ...     """Simple view subclass"""
+
+In testing mode we always have to register template manually because venusian can't scan test
+unit:
+
+    >>> factory = TemplateFactory(my_other_template, 'text/html')
+    >>> config.registry.registerAdapter(factory, (MyView2, IRequest), IContentTemplate)
+
+    >>> view = MyView2(root, request)
+    >>> print(view())
+    <div>This is my template for view 2</div>
+
+    >>> tearDown()

--- a/src/pyams_template/doctests/README.txt	Tue Nov 26 10:09:26 2019 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,4 +0,0 @@
-======================
-pyams_template package
-======================
-