# HG changeset patch
# User cmlenz
# Date 1174567518 0
# Node ID 5b248708bbed626635d6b1683e8a21b2ec86e159
# Parent  d698a5556a550bf2fcd8a6c8c90a5661c7e48276
Try to use proper reStructuredText for docstrings throughout.

diff --git a/genshi/__init__.py b/genshi/__init__.py
--- a/genshi/__init__.py
+++ b/genshi/__init__.py
@@ -19,6 +19,7 @@
 independently of where or how they are produced.
 """
 
+__docformat__ = 'restructuredtext en'
 try:
     __version__ = __import__('pkg_resources').get_distribution('Genshi').version
 except ImportError:
diff --git a/genshi/builder.py b/genshi/builder.py
--- a/genshi/builder.py
+++ b/genshi/builder.py
@@ -11,9 +11,12 @@
 # individuals. For the exact contribution history, see the revision
 # history and logs, available at http://genshi.edgewall.org/log/.
 
+"""Support for programmatically generating markup streams."""
+
 from genshi.core import Attrs, Namespace, QName, Stream, START, END, TEXT
 
 __all__ = ['Fragment', 'Element', 'tag']
+__docformat__ = 'restructuredtext en'
 
 
 class Fragment(object):
@@ -229,8 +232,8 @@
     def __init__(self, namespace=None):
         """Create the factory, optionally bound to the given namespace.
         
-        @param namespace: the namespace URI for any created elements, or `None`
-            for no namespace
+        :param namespace: the namespace URI for any created elements, or `None`
+                          for no namespace
         """
         if namespace and not isinstance(namespace, Namespace):
             namespace = Namespace(namespace)
diff --git a/genshi/core.py b/genshi/core.py
--- a/genshi/core.py
+++ b/genshi/core.py
@@ -19,6 +19,7 @@
 
 __all__ = ['Stream', 'Markup', 'escape', 'unescape', 'Attrs', 'Namespace',
            'QName']
+__docformat__ = 'restructuredtext en'
 
 
 class StreamEventKind(str):
@@ -35,14 +36,15 @@
     
     This class is basically an iterator over the events.
     
-    Stream events are tuples of the form:
+    Stream events are tuples of the form::
     
       (kind, data, position)
     
-    where `kind` is the event kind (such as `START`, `END`, `TEXT`, etc), `data`
-    depends on the kind of event, and `position` is a `(filename, line, offset)`
-    tuple that contains the location of the original element or text in the
-    input. If the original location is unknown, `position` is `(None, -1, -1)`.
+    where ``kind`` is the event kind (such as `START`, `END`, `TEXT`, etc),
+    ``data`` depends on the kind of event, and ``position`` is a
+    ``(filename, line, offset)`` tuple that contains the location of the
+    original element or text in the input. If the original location is unknown,
+    ``position`` is ``(None, -1, -1)``.
     
     Also provided are ways to serialize the stream to text. The `serialize()`
     method will return an iterator over generated strings, while `render()`
@@ -65,7 +67,7 @@
     def __init__(self, events):
         """Initialize the stream with a sequence of markup events.
         
-        @param events: a sequence or iterable providing the events
+        :param events: a sequence or iterable providing the events
         """
         self.events = events
 
@@ -121,11 +123,11 @@
         filters must be callables that accept the stream object as parameter,
         and return the filtered stream.
         
-        The call:
+        The call::
         
             stream.filter(filter1, filter2)
         
-        is equivalent to:
+        is equivalent to::
         
             stream | filter1 | filter2
         """
@@ -134,10 +136,10 @@
     def render(self, method='xml', encoding='utf-8', **kwargs):
         """Return a string representation of the stream.
         
-        @param method: determines how the stream is serialized; can be either
+        :param method: determines how the stream is serialized; can be either
                        "xml", "xhtml", "html", "text", or a custom serializer
                        class
-        @param encoding: how the output string should be encoded; if set to
+        :param encoding: how the output string should be encoded; if set to
                          `None`, this method returns a `unicode` object
 
         Any additional keyword arguments are passed to the serializer, and thus
@@ -156,7 +158,7 @@
         """Return a new stream that contains the events matching the given
         XPath expression.
         
-        @param path: a string containing the XPath expression
+        :param path: a string containing the XPath expression
         """
         from genshi.path import Path
         return Path(path).select(self, namespaces, variables)
@@ -169,7 +171,7 @@
         the serialized output incrementally, as opposed to returning a single
         string.
         
-        @param method: determines how the stream is serialized; can be either
+        :param method: determines how the stream is serialized; can be either
                        "xml", "xhtml", "html", "text", or a custom serializer
                        class
 
@@ -231,11 +233,11 @@
     >>> attrs.get('title')
     'Foo'
     
-    Instances may not be manipulated directly. Instead, the operators `|` and
-    `-` can be used to produce new instances that have specific attributes
+    Instances may not be manipulated directly. Instead, the operators ``|`` and
+    ``-`` can be used to produce new instances that have specific attributes
     added, replaced or removed.
     
-    To remove an attribute, use the `-` operator. The right hand side can be
+    To remove an attribute, use the ``-`` operator. The right hand side can be
     either a string or a set/sequence of strings, identifying the name(s) of
     the attribute(s) to remove:
     
@@ -253,8 +255,9 @@
     >>> attrs
     Attrs([('href', '#')])
     
-    To add a new attribute, use the `|` operator, where the right hand value
-    is a sequence of `(name, value)` tuples (which includes `Attrs` instances):
+    To add a new attribute, use the ``|`` operator, where the right hand value
+    is a sequence of ``(name, value)`` tuples (which includes `Attrs`
+    instances):
     
     >>> attrs | [('title', 'Bar')]
     Attrs([('href', '#'), ('title', 'Bar')])
@@ -264,7 +267,6 @@
     
     >>> attrs | [('href', 'http://example.org/')]
     Attrs([('href', 'http://example.org/')])
-    
     """
     __slots__ = []
 
@@ -312,7 +314,7 @@
     def totuple(self):
         """Return the attributes as a markup event.
         
-        The returned event is a TEXT event, the data is the value of all
+        The returned event is a `TEXT` event, the data is the value of all
         attributes joined together.
         """
         return TEXT, u''.join([x[1] for x in self]), (None, -1, -1)
@@ -438,7 +440,7 @@
     QName(u'http://www.w3.org/1999/xhtml}body')
     
     A `Namespace` object can also be used to test whether a specific `QName`
-    belongs to that namespace using the `in` operator:
+    belongs to that namespace using the ``in`` operator:
     
     >>> qname = html.body
     >>> qname in html
@@ -496,7 +498,7 @@
     """A qualified element or attribute name.
     
     The unicode value of instances of this class contains the qualified name of
-    the element or attribute, in the form `{namespace}localname`. The namespace
+    the element or attribute, in the form ``{namespace}localname``. The namespace
     URI can be obtained through the additional `namespace` attribute, while the
     local name can be accessed through the `localname` attribute.
     
diff --git a/genshi/filters.py b/genshi/filters.py
--- a/genshi/filters.py
+++ b/genshi/filters.py
@@ -23,6 +23,7 @@
 from genshi.core import END, START, TEXT
 
 __all__ = ['HTMLFormFiller', 'HTMLSanitizer']
+__docformat__ = 'restructuredtext en'
 
 
 class HTMLFormFiller(object):
@@ -45,14 +46,15 @@
     def __init__(self, name=None, id=None, data=None):
         """Create the filter.
         
-        @param name: The name of the form that should be populated. If this
-            parameter is given, only forms where the ``name`` attribute value
-            matches the parameter are processed.
-        @param id: The ID of the form that should be populated. If this
-            parameter is given, only forms where the ``id`` attribute value
-            matches the parameter are processed.
-        @param data: The dictionary of form values, where the keys are the names
-            of the form fields, and the values are the values to fill in.
+        :param name: The name of the form that should be populated. If this
+                     parameter is given, only forms where the ``name`` attribute
+                     value matches the parameter are processed.
+        :param id: The ID of the form that should be populated. If this
+                   parameter is given, only forms where the ``id`` attribute
+                   value matches the parameter are processed.
+        :param data: The dictionary of form values, where the keys are the names
+                     of the form fields, and the values are the values to fill
+                     in.
         """
         self.name = name
         self.id = id
@@ -63,8 +65,8 @@
     def __call__(self, stream, ctxt=None):
         """Apply the filter to the given stream.
         
-        @param stream: the markup event stream to filter
-        @param ctxt: the template context (unused)
+        :param stream: the markup event stream to filter
+        :param ctxt: the template context (unused)
         """
         in_form = in_select = in_option = in_textarea = False
         select_value = option_value = textarea_value = None
@@ -213,10 +215,10 @@
         
         The exact set of allowed elements and attributes can be configured.
         
-        @param safe_tags: a set of tag names that are considered safe
-        @param safe_attrs: a set of attribute names that are considered safe
-        @param safe_schemes: a set of URI schemes that are considered safe
-        @param uri_attrs: a set of names of attributes that contain URIs
+        :param safe_tags: a set of tag names that are considered safe
+        :param safe_attrs: a set of attribute names that are considered safe
+        :param safe_schemes: a set of URI schemes that are considered safe
+        :param uri_attrs: a set of names of attributes that contain URIs
         """
         self.safe_tags = safe_tags
         self.safe_attrs = safe_attrs
@@ -226,8 +228,8 @@
     def __call__(self, stream, ctxt=None):
         """Apply the filter to the given stream.
         
-        @param stream: the markup event stream to filter
-        @param ctxt: the template context (unused)
+        :param stream: the markup event stream to filter
+        :param ctxt: the template context (unused)
         """
         waiting_for = None
 
diff --git a/genshi/input.py b/genshi/input.py
--- a/genshi/input.py
+++ b/genshi/input.py
@@ -11,6 +11,10 @@
 # individuals. For the exact contribution history, see the revision
 # history and logs, available at http://genshi.edgewall.org/log/.
 
+"""Support for constructing markup streams from files, strings, or other
+sources.
+"""
+
 from itertools import chain
 from xml.parsers import expat
 try:
@@ -27,6 +31,7 @@
                         START_CDATA, END_CDATA, PI, COMMENT
 
 __all__ = ['ET', 'ParseError', 'XMLParser', 'XML', 'HTMLParser', 'HTML']
+__docformat__ = 'restructuredtext en'
 
 def ET(element):
     """Convert a given ElementTree element to a markup stream."""
@@ -81,11 +86,12 @@
     def __init__(self, source, filename=None, encoding=None):
         """Initialize the parser for the given XML input.
         
-        @param source: the XML text as a file-like object
-        @param filename: the name of the file, if appropriate
-        @param encoding: the encoding of the file; if not specified, the
-            encoding is assumed to be ASCII, UTF-8, or UTF-16, or whatever the
-            encoding specified in the XML declaration (if any)
+        :param source: the XML text as a file-like object
+        :param filename: the name of the file, if appropriate
+        :param encoding: the encoding of the file; if not specified, the
+                         encoding is assumed to be ASCII, UTF-8, or UTF-16, or
+                         whatever the encoding specified in the XML declaration
+                         (if any)
         """
         self.source = source
         self.filename = filename
@@ -259,9 +265,9 @@
     def __init__(self, source, filename=None, encoding='utf-8'):
         """Initialize the parser for the given HTML input.
         
-        @param source: the HTML text as a file-like object
-        @param filename: the name of the file, if known
-        @param filename: encoding of the file; ignored if the input is unicode
+        :param source: the HTML text as a file-like object
+        :param filename: the name of the file, if known
+        :param filename: encoding of the file; ignored if the input is unicode
         """
         html.HTMLParser.__init__(self)
         self.source = source
diff --git a/genshi/output.py b/genshi/output.py
--- a/genshi/output.py
+++ b/genshi/output.py
@@ -28,6 +28,7 @@
 
 __all__ = ['DocType', 'XMLSerializer', 'XHTMLSerializer', 'HTMLSerializer',
            'TextSerializer']
+__docformat__ = 'restructuredtext en'
 
 
 class DocType(object):
@@ -69,11 +70,11 @@
                  namespace_prefixes=None):
         """Initialize the XML serializer.
         
-        @param doctype: a `(name, pubid, sysid)` tuple that represents the
-            DOCTYPE declaration that should be included at the top of the
-            generated output
-        @param strip_whitespace: whether extraneous whitespace should be
-            stripped from the output
+        :param doctype: a ``(name, pubid, sysid)`` tuple that represents the
+                        DOCTYPE declaration that should be included at the top
+                        of the generated output
+        :param strip_whitespace: whether extraneous whitespace should be
+                                 stripped from the output
         """
         self.preamble = []
         if doctype:
@@ -248,11 +249,11 @@
     def __init__(self, doctype=None, strip_whitespace=True):
         """Initialize the HTML serializer.
         
-        @param doctype: a `(name, pubid, sysid)` tuple that represents the
-            DOCTYPE declaration that should be included at the top of the
-            generated output
-        @param strip_whitespace: whether extraneous whitespace should be
-            stripped from the output
+        :param doctype: a ``(name, pubid, sysid)`` tuple that represents the
+                        DOCTYPE declaration that should be included at the top
+                        of the generated output
+        :param strip_whitespace: whether extraneous whitespace should be
+                                 stripped from the output
         """
         super(HTMLSerializer, self).__init__(doctype, False)
         self.filters = [EmptyTagFilter()]
@@ -381,7 +382,7 @@
     r"""Output stream filter that removes namespace information from the stream,
     instead adding namespace attributes and prefixes as needed.
     
-    @param prefixes: optional mapping of namespace URIs to prefixes
+    :param prefixes: optional mapping of namespace URIs to prefixes
     
     >>> from genshi.input import XML
     >>> xml = XML('''<doc xmlns="NS1" xmlns:two="NS2">
@@ -492,8 +493,9 @@
     r"""Stream filter that removes all namespace information from a stream, and
     optionally strips out all tags not in a given namespace.
     
-    @param namespace: the URI of the namespace that should not be stripped. If
-        not set, only elements with no namespace are included in the output.
+    :param namespace: the URI of the namespace that should not be stripped. If
+                      not set, only elements with no namespace are included in
+                      the output.
     
     >>> from genshi.input import XML
     >>> xml = XML('''<doc xmlns="NS1" xmlns:two="NS2">
@@ -549,13 +551,14 @@
     def __init__(self, preserve=None, noescape=None):
         """Initialize the filter.
         
-        @param preserve: a set or sequence of tag names for which white-space
-            should be preserved
-        @param noescape: a set or sequence of tag names for which text content
-            should not be escaped
+        :param preserve: a set or sequence of tag names for which white-space
+                         should be preserved
+        :param noescape: a set or sequence of tag names for which text content
+                         should not be escaped
         
         The `noescape` set is expected to refer to elements that cannot contain
-        further child elements (such as <style> or <script> in HTML documents).
+        further child elements (such as ``<style>`` or ``<script>`` in HTML
+        documents).
         """
         if preserve is None:
             preserve = []
diff --git a/genshi/path.py b/genshi/path.py
--- a/genshi/path.py
+++ b/genshi/path.py
@@ -38,6 +38,7 @@
 from genshi.core import START, END, TEXT, COMMENT, PI
 
 __all__ = ['Path', 'PathSyntaxError']
+__docformat__ = 'restructuredtext en'
 
 
 class Axis(object):
@@ -75,7 +76,7 @@
     def __init__(self, text, filename=None, lineno=-1):
         """Create the path object from a string.
         
-        @param text: the path expression
+        :param text: the path expression
         """
         self.source = text
         self.paths = PathParser(text, filename, lineno).parse()
@@ -105,10 +106,10 @@
         >>> print Path('.//child/text()').select(xml)
         Text
         
-        @param stream: the stream to select from
-        @param namespaces: (optional) a mapping of namespace prefixes to URIs
-        @param variables: (optional) a mapping of variable names to values
-        @return: the substream matching the path, or an empty stream
+        :param stream: the stream to select from
+        :param namespaces: (optional) a mapping of namespace prefixes to URIs
+        :param variables: (optional) a mapping of variable names to values
+        :return: the substream matching the path, or an empty stream
         """
         if namespaces is None:
             namespaces = {}
@@ -140,16 +141,16 @@
         """Returns a function that can be used to track whether the path matches
         a specific stream event.
         
-        The function returned expects the positional arguments `event`,
-        `namespaces` and `variables`. The first is a stream event, while the
+        The function returned expects the positional arguments ``event``,
+        ``namespaces`` and ``variables``. The first is a stream event, while the
         latter two are a mapping of namespace prefixes to URIs, and a mapping
         of variable names to values, respectively. In addition, the function
-        accepts an `updateonly` keyword argument that default to `False`. If
-        it is set to `True`, the function only updates its internal state,
+        accepts an ``updateonly`` keyword argument that default to ``False``. If
+        it is set to ``True``, the function only updates its internal state,
         but does not perform any tests or return a result.
         
         If the path matches the event, the function returns the match (for
-        example, a `START` or `TEXT` event.) Otherwise, it returns `None`.
+        example, a `START` or `TEXT` event.) Otherwise, it returns ``None``.
         
         >>> from genshi.input import XML
         >>> xml = XML('<root><elem><child id="1"/></elem><child id="2"/></root>')
diff --git a/genshi/template/__init__.py b/genshi/template/__init__.py
--- a/genshi/template/__init__.py
+++ b/genshi/template/__init__.py
@@ -19,3 +19,5 @@
 from genshi.template.loader import TemplateLoader, TemplateNotFound
 from genshi.template.markup import MarkupTemplate
 from genshi.template.text import TextTemplate
+
+__docformat__ = 'restructuredtext en'
diff --git a/genshi/template/base.py b/genshi/template/base.py
--- a/genshi/template/base.py
+++ b/genshi/template/base.py
@@ -24,6 +24,7 @@
 
 __all__ = ['Context', 'Template', 'TemplateError', 'TemplateRuntimeError',
            'TemplateSyntaxError', 'BadDirectiveError']
+__docformat__ = 'restructuredtext en'
 
 
 class TemplateError(Exception):
diff --git a/genshi/template/directives.py b/genshi/template/directives.py
--- a/genshi/template/directives.py
+++ b/genshi/template/directives.py
@@ -25,6 +25,7 @@
            'DefDirective', 'ForDirective', 'IfDirective', 'MatchDirective',
            'OtherwiseDirective', 'ReplaceDirective', 'StripDirective',
            'WhenDirective', 'WithDirective']
+__docformat__ = 'restructuredtext en'
 
 
 class DirectiveMeta(type):
@@ -39,8 +40,8 @@
     """Abstract base class for template directives.
     
     A directive is basically a callable that takes three positional arguments:
-    `ctxt` is the template data context, `stream` is an iterable over the
-    events that the directive applies to, and `directives` is is a list of
+    ``ctxt`` is the template data context, ``stream`` is an iterable over the
+    events that the directive applies to, and ``directives`` is is a list of
     other directives on the same stream that need to be applied.
     
     Directives can be "anonymous" or "registered". Registered directives can be
@@ -63,15 +64,15 @@
     def attach(cls, template, stream, value, namespaces, pos):
         """Called after the template stream has been completely parsed.
         
-        @param template: the `Template` object
-        @param stream: the event stream associated with the directive
-        @param value: the argument value for the directive
-        @param namespaces: a mapping of namespace URIs to prefixes
-        @param pos: a `(filename, lineno, offset)` tuple describing the location
-            where the directive was found in the source
+        :param template: the `Template` object
+        :param stream: the event stream associated with the directive
+        :param value: the argument value for the directive
+        :param namespaces: a mapping of namespace URIs to prefixes
+        :param pos: a ``(filename, lineno, offset)`` tuple describing the
+                    location where the directive was found in the source
         
-        This class method should return a `(directive, stream)` tuple. If
-        `directive` is not `None`, it should be an instance of the `Directive`
+        This class method should return a ``(directive, stream)`` tuple. If
+        ``directive`` is not ``None``, it should be an instance of the `Directive`
         class, and gets added to the list of directives applied to the substream
         at runtime. `stream` is an event stream that replaces the original
         stream associated with the directive.
@@ -82,10 +83,10 @@
     def __call__(self, stream, ctxt, directives):
         """Apply the directive to the given stream.
         
-        @param stream: the event stream
-        @param ctxt: the context data
-        @param directives: a list of the remaining directives that should
-            process the stream
+        :param stream: the event stream
+        :param ctxt: the context data
+        :param directives: a list of the remaining directives that should
+                           process the stream
         """
         raise NotImplementedError
 
@@ -128,10 +129,10 @@
 
 
 class AttrsDirective(Directive):
-    """Implementation of the `py:attrs` template directive.
+    """Implementation of the ``py:attrs`` template directive.
     
-    The value of the `py:attrs` attribute should be a dictionary or a sequence
-    of `(name, value)` tuples. The items in that dictionary or sequence are
+    The value of the ``py:attrs`` attribute should be a dictionary or a sequence
+    of ``(name, value)`` tuples. The items in that dictionary or sequence are
     added as attributes to the element:
     
     >>> from genshi.template import MarkupTemplate
@@ -147,7 +148,7 @@
       <li class="collapse">Bar</li>
     </ul>
     
-    If the value evaluates to `None` (or any other non-truth value), no
+    If the value evaluates to ``None`` (or any other non-truth value), no
     attributes are added:
     
     >>> print tmpl.generate(foo=None)
@@ -180,10 +181,10 @@
 
 
 class ContentDirective(Directive):
-    """Implementation of the `py:content` template directive.
+    """Implementation of the ``py:content`` template directive.
     
     This directive replaces the content of the element with the result of
-    evaluating the value of the `py:content` attribute:
+    evaluating the value of the ``py:content`` attribute:
     
     >>> from genshi.template import MarkupTemplate
     >>> tmpl = MarkupTemplate('''<ul xmlns:py="http://genshi.edgewall.org/">
@@ -203,7 +204,7 @@
 
 
 class DefDirective(Directive):
-    """Implementation of the `py:def` template directive.
+    """Implementation of the ``py:def`` template directive.
     
     This directive can be used to create "Named Template Functions", which
     are template snippets that are not actually output during normal
@@ -302,7 +303,7 @@
 
 
 class ForDirective(Directive):
-    """Implementation of the `py:for` template directive for repeating an
+    """Implementation of the ``py:for`` template directive for repeating an
     element based on an iterable in the context data.
     
     >>> from genshi.template import MarkupTemplate
@@ -354,7 +355,7 @@
 
 
 class IfDirective(Directive):
-    """Implementation of the `py:if` template directive for conditionally
+    """Implementation of the ``py:if`` template directive for conditionally
     excluding elements from being output.
     
     >>> from genshi.template import MarkupTemplate
@@ -377,7 +378,7 @@
 
 
 class MatchDirective(Directive):
-    """Implementation of the `py:match` template directive.
+    """Implementation of the ``py:match`` template directive.
 
     >>> from genshi.template import MarkupTemplate
     >>> tmpl = MarkupTemplate('''<div xmlns:py="http://genshi.edgewall.org/">
@@ -414,10 +415,10 @@
 
 
 class ReplaceDirective(Directive):
-    """Implementation of the `py:replace` template directive.
+    """Implementation of the ``py:replace`` template directive.
     
     This directive replaces the element with the result of evaluating the
-    value of the `py:replace` attribute:
+    value of the ``py:replace`` attribute:
     
     >>> from genshi.template import MarkupTemplate
     >>> tmpl = MarkupTemplate('''<div xmlns:py="http://genshi.edgewall.org/">
@@ -428,7 +429,7 @@
       Bye
     </div>
     
-    This directive is equivalent to `py:content` combined with `py:strip`,
+    This directive is equivalent to ``py:content`` combined with ``py:strip``,
     providing a less verbose way to achieve the same effect:
     
     >>> tmpl = MarkupTemplate('''<div xmlns:py="http://genshi.edgewall.org/">
@@ -448,10 +449,10 @@
 
 
 class StripDirective(Directive):
-    """Implementation of the `py:strip` template directive.
+    """Implementation of the ``py:strip`` template directive.
     
-    When the value of the `py:strip` attribute evaluates to `True`, the element
-    is stripped from the output
+    When the value of the ``py:strip`` attribute evaluates to ``True``, the
+    element is stripped from the output
     
     >>> from genshi.template import MarkupTemplate
     >>> tmpl = MarkupTemplate('''<div xmlns:py="http://genshi.edgewall.org/">
@@ -502,13 +503,13 @@
 
 
 class ChooseDirective(Directive):
-    """Implementation of the `py:choose` directive for conditionally selecting
+    """Implementation of the ``py:choose`` directive for conditionally selecting
     one of several body elements to display.
     
-    If the `py:choose` expression is empty the expressions of nested `py:when`
-    directives are tested for truth.  The first true `py:when` body is output.
-    If no `py:when` directive is matched then the fallback directive
-    `py:otherwise` will be used.
+    If the ``py:choose`` expression is empty the expressions of nested
+    ``py:when`` directives are tested for truth.  The first true ``py:when``
+    body is output. If no ``py:when`` directive is matched then the fallback
+    directive ``py:otherwise`` will be used.
     
     >>> from genshi.template import MarkupTemplate
     >>> tmpl = MarkupTemplate('''<div xmlns:py="http://genshi.edgewall.org/"
@@ -522,8 +523,9 @@
       <span>1</span>
     </div>
     
-    If the `py:choose` directive contains an expression, the nested `py:when`
-    directives are tested for equality to the `py:choose` expression:
+    If the ``py:choose`` directive contains an expression, the nested
+    ``py:when`` directives are tested for equality to the ``py:choose``
+    expression:
     
     >>> tmpl = MarkupTemplate('''<div xmlns:py="http://genshi.edgewall.org/"
     ...   py:choose="2">
@@ -535,9 +537,9 @@
       <span>2</span>
     </div>
     
-    Behavior is undefined if a `py:choose` block contains content outside a
-    `py:when` or `py:otherwise` block.  Behavior is also undefined if a
-    `py:otherwise` occurs before `py:when` blocks.
+    Behavior is undefined if a ``py:choose`` block contains content outside a
+    ``py:when`` or ``py:otherwise`` block.  Behavior is also undefined if a
+    ``py:otherwise`` occurs before ``py:when`` blocks.
     """
     __slots__ = ['matched', 'value']
 
@@ -554,10 +556,10 @@
 
 
 class WhenDirective(Directive):
-    """Implementation of the `py:when` directive for nesting in a parent with
-    the `py:choose` directive.
+    """Implementation of the ``py:when`` directive for nesting in a parent with
+    the ``py:choose`` directive.
     
-    See the documentation of `py:choose` for usage.
+    See the documentation of the `ChooseDirective` for usage.
     """
     __slots__ = ['filename']
 
@@ -596,10 +598,10 @@
 
 
 class OtherwiseDirective(Directive):
-    """Implementation of the `py:otherwise` directive for nesting in a parent
-    with the `py:choose` directive.
+    """Implementation of the ``py:otherwise`` directive for nesting in a parent
+    with the ``py:choose`` directive.
     
-    See the documentation of `py:choose` for usage.
+    See the documentation of `ChooseDirective` for usage.
     """
     __slots__ = ['filename']
 
@@ -622,7 +624,7 @@
 
 
 class WithDirective(Directive):
-    """Implementation of the `py:with` template directive, which allows
+    """Implementation of the ``py:with`` template directive, which allows
     shorthand access to variables and expressions.
     
     >>> from genshi.template import MarkupTemplate
diff --git a/genshi/template/eval.py b/genshi/template/eval.py
--- a/genshi/template/eval.py
+++ b/genshi/template/eval.py
@@ -28,6 +28,7 @@
 from genshi.util import flatten
 
 __all__ = ['Expression', 'Suite']
+__docformat__ = 'restructuredtext en'
 
 
 class Code(object):
@@ -37,11 +38,11 @@
     def __init__(self, source, filename=None, lineno=-1):
         """Create the code object, either from a string, or from an AST node.
         
-        @param source: either a string containing the source code, or an AST
-            node
-        @param filename: the (preferably absolute) name of the file containing
-            the code
-        @param lineno: the number of the line on which the code was found
+        :param source: either a string containing the source code, or an AST
+                       node
+        :param filename: the (preferably absolute) name of the file containing
+                         the code
+        :param lineno: the number of the line on which the code was found
         """
         if isinstance(source, basestring):
             self.source = source
@@ -91,7 +92,7 @@
     'thing'
     
     This also works the other way around: item access can be used to access
-    any object attribute (meaning there's no use for `getattr()` in templates):
+    any object attribute:
     
     >>> class MyClass(object):
     ...     myattr = 'Bar'
@@ -104,7 +105,7 @@
     'Bar'
     
     All of the standard Python operators are available to template expressions.
-    Built-in functions such as `len()` are also available in template
+    Built-in functions such as ``len()`` are also available in template
     expressions:
     
     >>> data = dict(items=[1, 2, 3])
@@ -117,8 +118,8 @@
     def evaluate(self, data):
         """Evaluate the expression against the given data dictionary.
         
-        @param data: a mapping containing the data to evaluate against
-        @return: the result of the evaluation
+        :param data: a mapping containing the data to evaluate against
+        :return: the result of the evaluation
         """
         __traceback_hide__ = 'before_and_this'
         return eval(self.code, {'data': data,
@@ -144,7 +145,7 @@
     def execute(self, data):
         """Execute the suite in the given data dictionary.
         
-        @param data: a mapping containing the data to execute in
+        :param data: a mapping containing the data to execute in
         """
         __traceback_hide__ = 'before_and_this'
         exec self.code in {'data': data,
@@ -166,7 +167,7 @@
 def _value_of(data):
     def value_of(name, default=None):
         """If a variable of the specified name is defined, return its value.
-        Otherwise, return the provided default value, or `None`.
+        Otherwise, return the provided default value, or ``None``.
         """
         return data.get(name, default)
     return value_of
diff --git a/genshi/template/interpolation.py b/genshi/template/interpolation.py
--- a/genshi/template/interpolation.py
+++ b/genshi/template/interpolation.py
@@ -24,6 +24,7 @@
 from genshi.template.eval import Expression
 
 __all__ = ['interpolate']
+__docformat__ = 'restructuredtext en'
 
 NAMESTART = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_'
 NAMECHARS = NAMESTART + '.0123456789'
@@ -32,21 +33,25 @@
 def interpolate(text, basedir=None, filename=None, lineno=-1, offset=0):
     """Parse the given string and extract expressions.
     
-    This method returns a list containing both literal text and `Expression`
-    objects.
+    This function is a generator that yields `TEXT` events for literal strings,
+    and `EXPR` events for expressions, depending on the results of parsing the
+    string.
     
     >>> for kind, data, pos in interpolate("$foo bar"):
     ...     print kind, `data`
     EXPR Expression('foo')
     TEXT u' bar'
     
-    @param text: the text to parse
-    @param basedir: base directory of the file in which the text was found
-        (optional)
-    @param filename: basename of the file in which the text was found (optional)
-    @param lineno: the line number at which the text was found (optional)
-    @param offset: the column number at which the text starts in the source
-        (optional)
+    :param text: the text to parse
+    :param basedir: base directory of the file in which the text was found
+                    (optional)
+    :param filename: basename of the file in which the text was found (optional)
+    :param lineno: the line number at which the text was found (optional)
+    :param offset: the column number at which the text starts in the source
+                   (optional)
+    :return: a list of `TEXT` and `EXPR` events
+    :raise TemplateSyntaxError: when a syntax error in an expression is
+                                encountered
     """
     filepath = filename
     if filepath and basedir:
diff --git a/genshi/template/loader.py b/genshi/template/loader.py
--- a/genshi/template/loader.py
+++ b/genshi/template/loader.py
@@ -23,6 +23,7 @@
 from genshi.util import LRUCache
 
 __all__ = ['TemplateLoader', 'TemplateNotFound']
+__docformat__ = 'restructuredtext en'
 
 
 class TemplateNotFound(TemplateError):
@@ -69,17 +70,17 @@
                  default_encoding=None, max_cache_size=25, default_class=None):
         """Create the template laoder.
         
-        @param search_path: a list of absolute path names that should be
-            searched for template files, or a string containing a single
-            absolute path
-        @param auto_reload: whether to check the last modification time of
-            template files, and reload them if they have changed
-        @param default_encoding: the default encoding to assume when loading
-            templates; defaults to UTF-8
-        @param max_cache_size: the maximum number of templates to keep in the
-            cache
-        @param default_class: the default `Template` subclass to use when
-            instantiating templates
+        :param search_path: a list of absolute path names that should be
+                            searched for template files, or a string containing
+                            a single absolute path
+        :param auto_reload: whether to check the last modification time of
+                            template files, and reload them if they have changed
+        :param default_encoding: the default encoding to assume when loading
+                                 templates; defaults to UTF-8
+        :param max_cache_size: the maximum number of templates to keep in the
+                               cache
+        :param default_class: the default `Template` subclass to use when
+                              instantiating templates
         """
         from genshi.template.markup import MarkupTemplate
 
@@ -109,19 +110,19 @@
         Template instances are cached to avoid having to parse the same
         template file more than once. Thus, subsequent calls of this method
         with the same template file name will return the same `Template`
-        object (unless the `auto_reload` option is enabled and the file was
+        object (unless the ``auto_reload`` option is enabled and the file was
         changed since the last parse.)
         
         If the `relative_to` parameter is provided, the `filename` is
         interpreted as being relative to that path.
         
-        @param filename: the relative path of the template file to load
-        @param relative_to: the filename of the template from which the new
-            template is being loaded, or `None` if the template is being loaded
-            directly
-        @param cls: the class of the template object to instantiate
-        @param encoding: the encoding of the template to load; defaults to the
-            `default_encoding` of the loader instance
+        :param filename: the relative path of the template file to load
+        :param relative_to: the filename of the template from which the new
+                            template is being loaded, or ``None`` if the template
+                            is being loaded directly
+        :param cls: the class of the template object to instantiate
+        :param encoding: the encoding of the template to load; defaults to the
+                         ``default_encoding`` of the loader instance
         """
         if cls is None:
             cls = self.default_class
diff --git a/genshi/template/markup.py b/genshi/template/markup.py
--- a/genshi/template/markup.py
+++ b/genshi/template/markup.py
@@ -32,6 +32,9 @@
 else:
     _ctxt2dict = lambda ctxt: ctxt
 
+__all__ = ['MarkupTemplate']
+__docformat__ = 'restructuredtext en'
+
 
 class MarkupTemplate(Template):
     """Implementation of the template language for XML-based templates.
@@ -221,8 +224,8 @@
             yield kind, data, pos
 
     def _exec(self, stream, ctxt):
-        """Internal stream filter that executes code in <?python ?> processing
-        instructions.
+        """Internal stream filter that executes code in ``<?python ?>``
+        processing instructions.
         """
         for event in stream:
             if event[0] is EXEC:
diff --git a/genshi/template/plugin.py b/genshi/template/plugin.py
--- a/genshi/template/plugin.py
+++ b/genshi/template/plugin.py
@@ -27,6 +27,7 @@
 
 __all__ = ['ConfigurationError', 'MarkupTemplateEnginePlugin',
            'TextTemplateEnginePlugin']
+__docformat__ = 'restructuredtext en'
 
 
 class ConfigurationError(Exception):
diff --git a/genshi/template/text.py b/genshi/template/text.py
--- a/genshi/template/text.py
+++ b/genshi/template/text.py
@@ -19,6 +19,9 @@
 from genshi.template.directives import *
 from genshi.template.interpolation import interpolate
 
+__all__ = ['TextTemplate']
+__docformat__ = 'restructuredtext en'
+
 
 class TextTemplate(Template):
     """Implementation of a simple text-based template engine.
diff --git a/genshi/util.py b/genshi/util.py
--- a/genshi/util.py
+++ b/genshi/util.py
@@ -16,6 +16,8 @@
 import htmlentitydefs
 import re
 
+__docformat__ = 'restructuredtext en'
+
 
 class LRUCache(dict):
     """A dictionary-like object that stores only a certain number of items, and