Build documents with Sphinx for RTD

Fixes #8

Run doctests with Sphinx on all versions as well.

5 files changed, 55 insertions, 132 deletions

diff --git a/src/zope/pagetemplate/architecture.txt b/src/zope/pagetemplate/architecture.txt
deleted file mode 100644
index 2d07ca4..0000000
--- a/src/zope/pagetemplate/architecture.txt
+++ /dev/null
@@ -1,31 +0,0 @@
-ZPT (Zope Page-Template) Architecture
-=====================================
-
-There are a number of major components that make up the page-template
-architecture: 
-
-- The TAL *compiler* and *interpreter*.  This is responsible for
-  compiling source files and for executing compiled templates.  See
-  the `zope.tal` package for more information.
-
-- An *expression engine* is responsible for compiling expressions and
-  for creating expression execution contexts.  It is common for
-  applications to override expression engines to provide custom
-  expression support or to change the way expressions are implemented.
-  The `zope.app.pagetemplate` package uses this to implement trusted
-  and untrusted evaluation; a different engine is used for each, with
-  different implementations of the same type of expressions.
-
-  Expression contexts support execution of expressions and provide
-  APIs for setting up variable scopes and setting variables.  The
-  expression contexts are passed to the TAL interpreter at execution
-  time.
-  
-  The most commonly used expression implementation is that found in
-  `zope.tales`.
-
-- Page templates tie everything together. They assemble an expression
-  engine with the TAL interpreter and orchestrate management of source
-  and compiled template data.  See `zope.pagetemplate.interfaces`.
-
-  
diff --git a/src/zope/pagetemplate/engine.py b/src/zope/pagetemplate/engine.py
index cea32d7..01df54c 100644
--- a/src/zope/pagetemplate/engine.py
+++ b/src/zope/pagetemplate/engine.py
@@ -170,6 +170,9 @@ class ZopeContext(ZopeContextBase):
         Therefore, this method removes any proxy from the evaluated
         expression.
 
+        >>> from zope.pagetemplate.engine import ZopeContext
+        >>> from zope.tales.tales import ExpressionEngine
+        >>> from zope.security.proxy import ProxyFactory
         >>> output = [('version', 'xxx'), ('mode', 'html'), ('other', 'things')]
         >>> def expression(context):
         ...     return ProxyFactory(output)
@@ -236,11 +239,13 @@ class AdapterNamespaces(object):
       >>> def adapter1(ob):
       ...     return 1
       >>> adapter1.__component_adapts__ = (None,)
+      >>> from zope.traversing.interfaces import IPathAdapter
       >>> provideAdapter(adapter1, None, IPathAdapter, 'a1')
 
     Now, with this adapter in place, we can try out the namespaces:
 
       >>> ob = object()
+      >>> from zope.pagetemplate.engine import AdapterNamespaces
       >>> namespaces = AdapterNamespaces()
       >>> namespace = namespaces['a1']
       >>> namespace(ob)
@@ -301,11 +306,13 @@ class ZopeBaseEngine(ExpressionEngine):
         return context
 
 class ZopeEngine(ZopeBaseEngine):
-    """Untrusted expression engine.
+    """
+    Untrusted expression engine.
 
     This engine does not allow modules to be imported; only modules
     already available may be accessed::
 
+      >>> from zope.pagetemplate.engine import _Engine
       >>> modname = 'zope.pagetemplate.tests.trusted'
       >>> engine = _Engine()
       >>> context = engine.getContext(engine.getBaseNames())
@@ -391,7 +398,7 @@ class ZopeEngine(ZopeBaseEngine):
 
     Note that this engine special-cases dicts during path traversal:
     it traverses only to their items, but not to their attributes
-    (e.g. methods on dicts), because of performance reasons:
+    (e.g. methods on dicts), because of performance reasons::
 
       >>> d = engine.getBaseNames()
       >>> d['adict'] = {'items': 123}
@@ -404,7 +411,7 @@ class ZopeEngine(ZopeBaseEngine):
         ...
       KeyError: 'keys'
 
-    This special-casing also applies to non-proxied dict subclasses:
+    This special-casing also applies to non-proxied dict subclasses::
 
       >>> class TraverserDict(dict):
       ...     def __init__(self):
@@ -433,10 +440,12 @@ class ZopeEngine(ZopeBaseEngine):
             super(ZopeEngine, self).getFunctionNamespace(namespacename))
 
 class TrustedZopeEngine(ZopeBaseEngine):
-    """Trusted expression engine.
+    """
+    Trusted expression engine.
 
     This engine allows modules to be imported::
 
+      >>> from zope.pagetemplate.engine import _TrustedEngine
       >>> modname = 'zope.pagetemplate.tests.trusted'
       >>> engine = _TrustedEngine()
       >>> context = engine.getContext(engine.getBaseNames())
@@ -450,7 +459,7 @@ class TrustedZopeEngine(ZopeBaseEngine):
       True
 
     Since this is trusted code, we can look at whatever is in the
-    module, not just __name__ or what's declared in a security
+    module, not just ``__name__`` or what's declared in a security
     assertion::
 
       >>> m.x
diff --git a/src/zope/pagetemplate/interfaces.py b/src/zope/pagetemplate/interfaces.py
index 4929b39..9a0fe71 100644
--- a/src/zope/pagetemplate/interfaces.py
+++ b/src/zope/pagetemplate/interfaces.py
@@ -25,8 +25,8 @@ class IPageTemplate(Interface):
 
         The argument handling is specific to particular
         implementations.  Normally, however, positional arguments are
-        bound to the top-level `args` variable and keyword arguments
-        are bound to the top-level `options` variable.
+        bound to the top-level ``args`` variable and keyword arguments
+        are bound to the top-level ``options`` variable.
         """
 
     def pt_edit(source, content_type):
@@ -39,7 +39,7 @@ class IPageTemplate(Interface):
         The errors may occur when the template is compiled or
         rendered.
 
-        `namespace` is the set of names passed to the TALES expression
+        *namespace* is the set of names passed to the TALES expression
         evaluator, similar to what's returned by pt_getContext().
 
         This can be used to let a template author know what went wrong
@@ -50,20 +50,20 @@ class IPageTemplate(Interface):
         """Get the template source
         """
 
-    macros = Attribute("An object that implements the __getitem__ "
-                       "protocol, containing page template macros.")
+    macros = Attribute("An object that implements the ``__getitem__`` "
+                       "protocol (e.g., a :class:`dict`), containing page template macros.")
 
 class IPageTemplateSubclassing(IPageTemplate):
     """Behavior that may be overridden or used by subclasses
     """
 
-    
+
     def pt_getContext(**kw):
         """Compute a dictionary of top-level template names
-        
+
         Responsible for returning the set of
         top-level names supported in path expressions
-        
+
         """
 
     def pt_getEngine():
@@ -79,7 +79,7 @@ class IPageTemplateSubclassing(IPageTemplate):
         This is sometimes overridden to provide additional argument
         binding.
         """
-        
+
     def pt_source_file():
         """return some text describing where a bit of ZPT code came from.
 
@@ -89,8 +89,8 @@ class IPageTemplateSubclassing(IPageTemplate):
     def _cook():
         """Compile the source
 
-        Results are saved in the variables: _v_errors, _v_warnings,
-        _v_program, and _v_macros, and the flag _v_cooked is set.
+        Results are saved in the variables: ``_v_errors``, ``_v_warnings``,
+        ``_v_program``, and ``_v_macros``, and the flag ``_v_cooked`` is set.
         """
     def _cook_check():
         """Compiles the source if necessary
@@ -115,8 +115,8 @@ class IPageTemplateEngine(Interface):
     def cook(source_file, text, engine, content_type):
         """Parse text and return prepared template program and macros.
 
-        Note that while ``source_file`` is provided to name the source
-        of the input ``text``, it should not be relied on to be an
+        Note that while *source_file* is provided to name the source
+        of the input *text*, it should not be relied on to be an
         actual filename (it may be an application-specific, virtual
         path).
 
@@ -128,36 +128,29 @@ class IPageTemplateProgram(Interface):
     """Cooked template program."""
 
     def __call__(
-        context, macros, debug=0, wrap=60, metal=1, tal=1, showtal=-1,
-        strictinsert=1, stackLimit=100, i18nInterpolate=1,
-        sourceAnnotations=0):
-        """Render template in the provided template ``context``.
+            context, macros, debug=0, wrap=60, metal=1, tal=1, showtal=-1,
+            strictinsert=1, stackLimit=100, i18nInterpolate=1,
+            sourceAnnotations=0):
+        """
+        Render template in the provided template *context*.
 
         Optional arguments:
 
-            debug -- enable debugging output to sys.stderr (off by default).
-
-            wrap -- try to wrap attributes on opening tags to this number of
+        :keyword bool debug: enable debugging output to sys.stderr (off by default).
+        :keyword int wrap: try to wrap attributes on opening tags to this number of
             column (default: 60).
-
-            metal -- enable METAL macro processing (on by default).
-
-            tal -- enable TAL processing (on by default).
-
-            showtal -- do not strip away TAL directives.  A special value of
+        :keyword bool metal: enable METAL macro processing (on by default).
+        :keyword bool tal: enable TAL processing (on by default).
+        :keyword int showtal: do not strip away TAL directives.  A special value of
             -1 (which is the default setting) enables showtal when TAL
             processing is disabled, and disables showtal when TAL processing is
             enabled.  Note that you must use 0, 1, or -1; true boolean values
             are not supported (for historical reasons).
-
-            strictinsert -- enable TAL processing and stricter HTML/XML
+        :keyword bool strictinsert: enable TAL processing and stricter HTML/XML
             checking on text produced by structure inserts (on by default).
             Note that Zope turns this value off by default.
-
-            stackLimit -- set macro nesting limit (default: 100).
-
-            i18nInterpolate -- enable i18n translations (default: on).
-
-            sourceAnnotations -- enable source annotations with HTML comments
+        :keyword int stackLimit: set macro nesting limit (default: 100).
+        :keyword bool i18nInterpolate: enable i18n translations (default: on).
+        :keyword bool sourceAnnotations: enable source annotations with HTML comments
             (default: off).
         """
diff --git a/src/zope/pagetemplate/pagetemplate.py b/src/zope/pagetemplate/pagetemplate.py
index 9c05c89..81b2c8b 100644
--- a/src/zope/pagetemplate/pagetemplate.py
+++ b/src/zope/pagetemplate/pagetemplate.py
@@ -34,8 +34,7 @@ _default_options = {}
 
 
 class StringIO(list):
-    """Unicode aware append-only version of StringIO.
-    """
+    # Unicode aware append-only version of StringIO.
     write = list.append
 
     def __init__(self, value=None):
@@ -49,25 +48,27 @@ class StringIO(list):
 
 @implementer(IPageTemplateSubclassing)
 class PageTemplate(object):
-    """Page Templates using TAL, TALES, and METAL.
+    """
+    Page Templates using TAL, TALES, and METAL.
+
+    **Subclassing**
 
-    Subclassing
-    -----------
+    This class implements :class:`~zope.pagetemplate.interfaces.IPageTemplateSubclassing`.
 
     The following methods have certain internal responsibilities.
 
-    pt_getContext(**keywords)
+    ``pt_getContext(**keywords)``
         Should ignore keyword arguments that it doesn't care about,
         and construct the namespace passed to the TALES expression
         engine.  This method is free to use the keyword arguments it
         receives.
 
-    pt_render(namespace, source=False, sourceAnnotations=False, showtal=False)
+    ``pt_render(namespace, source=False, sourceAnnotations=False, showtal=False)``
         Responsible the TAL interpreter to perform the rendering.  The
         namespace argument is a mapping which defines the top-level
         namespaces passed to the TALES expression engine.
 
-    __call__(*args, **keywords)
+    ``__call__(*args, **keywords)``
         Calls pt_getContext() to construct the top-level namespace
         passed to the TALES expression engine, then calls pt_render()
         to perform the rendering.
@@ -245,7 +246,11 @@ class PTRuntimeError(RuntimeError):
 @implementer(IPageTemplateProgram)
 @provider(IPageTemplateEngine)
 class PageTemplateEngine(object):
-    """Page template engine that uses the TAL interpreter to render."""
+    """
+    Page template engine that uses the TAL interpreter to render.
+
+    This class implements :class:`zope.pagetemplate.interfaces.IPageTemplateProgram`.
+    """
 
 
     def __init__(self, program):
diff --git a/src/zope/pagetemplate/readme.txt b/src/zope/pagetemplate/readme.txt
deleted file mode 100644
index 85f6fda..0000000
--- a/src/zope/pagetemplate/readme.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-ZPT Usage
-=========
-
-This document focuses on usage of Page Templates outside of a Zope
-context, it does *not* explain how to write page templates as there
-are several resources on the web which do so.
-
-Simple Usage
-------------
-
-Using Page Templates outside of Zope3 is very easy and straight
-forward.  A quick example::
-
-  >>> from zope.pagetemplate.pagetemplatefile import PageTemplateFile
-  >>> my_pt = PageTemplateFile('hello_world.pt')
-  >>> my_pt()
-  u'<html><body>Hello World</body></html>'
-
-Subclassing PageTemplates
--------------------------
-
-Lets say we want to alter page templates such that keyword arguments
-appear as top level items in the namespace.  We can subclass
-`PageTemplate` and alter the default behavior of `pt_getContext()` to
-add them in::
-
-  from zope.pagetemplate.pagetemplate import PageTemplate
-
-  class mypt(PageTemplate):
-      def pt_getContext(self, args=(), options={}, **kw):
-         rval = PageTemplate.pt_getContext(self, args=args)
-         options.update(rval)
-         return options
-
-  class foo:
-      def getContents(self): return 'hi'
-
-So now we can bind objects in a more arbitrary fashion, like the
-following::
-
-  template = """
-  <html>
-  <body>
-  <b tal:replace="das_object/getContents">Good Stuff Here</b>
-  </body>
-  </html>
-  """
-
-  pt = mypt()
-  pt.write(template)
-  pt(das_object=foo())
-
-See `interfaces.py`.