# HG changeset patch
# User cmlenz
# Date 1174575929 0
# Node ID 68a8308309b954c104e3d1a5ba8ef4738201d567
# Parent  a0711da164ac9026adeb2cf2246ed2501fde4967
More API documentation.

diff --git a/doc/epydoc.conf b/doc/epydoc.conf
--- a/doc/epydoc.conf
+++ b/doc/epydoc.conf
@@ -1,7 +1,7 @@
 [epydoc]
 
-name: Genshi
-url: http://genshi.edgewall.org/
+name: Documentation Index
+url: ../index.html
 modules: genshi
 verbosity: 1
 
diff --git a/doc/index.txt b/doc/index.txt
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -25,3 +25,4 @@
 * `Genshi XML Template Language <xml-templates.html>`_
 * `Genshi Text Template Language <text-templates.html>`_
 * `Using XPath in Genshi <xpath.html>`_
+* `Generated API Documentation <api/index.html>`_
diff --git a/genshi/core.py b/genshi/core.py
--- a/genshi/core.py
+++ b/genshi/core.py
@@ -53,16 +53,16 @@
     """
     __slots__ = ['events']
 
-    START = StreamEventKind('START') # a start tag
-    END = StreamEventKind('END') # an end tag
-    TEXT = StreamEventKind('TEXT') # literal text
-    DOCTYPE = StreamEventKind('DOCTYPE') # doctype declaration
-    START_NS = StreamEventKind('START_NS') # start namespace mapping
-    END_NS = StreamEventKind('END_NS') # end namespace mapping
-    START_CDATA = StreamEventKind('START_CDATA') # start CDATA section
-    END_CDATA = StreamEventKind('END_CDATA') # end CDATA section
-    PI = StreamEventKind('PI') # processing instruction
-    COMMENT = StreamEventKind('COMMENT') # comment
+    START = StreamEventKind('START') #: a start tag
+    END = StreamEventKind('END') #: an end tag
+    TEXT = StreamEventKind('TEXT') #: literal text
+    DOCTYPE = StreamEventKind('DOCTYPE') #: doctype declaration
+    START_NS = StreamEventKind('START_NS') #: start namespace mapping
+    END_NS = StreamEventKind('END_NS') #: end namespace mapping
+    START_CDATA = StreamEventKind('START_CDATA') #: start CDATA section
+    END_CDATA = StreamEventKind('END_CDATA') #: end CDATA section
+    PI = StreamEventKind('PI') #: processing instruction
+    COMMENT = StreamEventKind('COMMENT') #: comment
 
     def __init__(self, events):
         """Initialize the stream with a sequence of markup events.
diff --git a/genshi/template/base.py b/genshi/template/base.py
--- a/genshi/template/base.py
+++ b/genshi/template/base.py
@@ -11,6 +11,8 @@
 # individuals. For the exact contribution history, see the revision
 # history and logs, available at http://genshi.edgewall.org/log/.
 
+"""Basic templating functionality."""
+
 try:
     from collections import deque
 except ImportError:
@@ -197,12 +199,30 @@
     """
     __metaclass__ = TemplateMeta
 
-    EXPR = StreamEventKind('EXPR') # an expression
-    SUB = StreamEventKind('SUB') # a "subprogram"
+    EXPR = StreamEventKind('EXPR')
+    """Stream event kind representing a Python expression."""
+
+    SUB = StreamEventKind('SUB')
+    """Stream event kind representing a nested stream to which one or more
+    directives should be applied.
+    """
 
     def __init__(self, source, basedir=None, filename=None, loader=None,
                  encoding=None):
-        """Initialize a template from either a string or a file-like object."""
+        """Initialize a template from either a string, a file-like object, or
+        an already parsed markup stream.
+        
+        :param source: a string, file-like object, or markup stream to read the
+                       template from
+        :param basedir: the base directory containing the template file; when
+                        loaded from a `TemplateLoader`, this will be the
+                        directory on the template search path in which the
+                        template was found
+        :param filename: the name of the template file, relative to the given
+                         base directory
+        :param loader: the `TemplateLoader` to use for load included templates
+        :param encoding: the encoding of the `source`
+        """
         self.basedir = basedir
         self.filename = filename
         if basedir and filename:
@@ -228,11 +248,18 @@
         directives that will be executed in the render stage. The input is
         split up into literal output (text that does not depend on the context
         data) and directives or expressions.
+        
+        :param source: a file-like object containing the XML source of the
+                       template, or an XML event stream
+        :param encoding: the encoding of the `source`
         """
         raise NotImplementedError
 
     def _prepare(self, stream):
-        """Call the `attach` method of every directive found in the template."""
+        """Call the `attach` method of every directive found in the template.
+        
+        :param stream: the event stream of the template
+        """
         for kind, data, pos in stream:
             if kind is SUB:
                 directives = []
@@ -261,8 +288,8 @@
         an instance of the `Context` class, and keyword arguments are ignored.
         This calling style is used for internal processing.
         
-        @return: a markup event stream representing the result of applying
-            the template to the context data.
+        :return: a markup event stream representing the result of applying
+                 the template to the context data.
         """
         if args:
             assert len(args) == 1
diff --git a/genshi/template/markup.py b/genshi/template/markup.py
--- a/genshi/template/markup.py
+++ b/genshi/template/markup.py
@@ -48,7 +48,10 @@
     </ul>
     """
     EXEC = StreamEventKind('EXEC')
+    """Stream event kind representing a Python code suite to execute."""
+
     INCLUDE = StreamEventKind('INCLUDE')
+    """Stream event kind representing the inclusion of another template."""
 
     DIRECTIVE_NAMESPACE = Namespace('http://genshi.edgewall.org/')
     XINCLUDE_NAMESPACE = Namespace('http://www.w3.org/2001/XInclude')
@@ -68,7 +71,6 @@
 
     def __init__(self, source, basedir=None, filename=None, loader=None,
                  encoding=None):
-        """Initialize a template from either a string or a file-like object."""
         Template.__init__(self, source, basedir=basedir, filename=filename,
                           loader=loader, encoding=encoding)
 
@@ -77,7 +79,6 @@
             self.filters.append(self._include)
 
     def _parse(self, source, encoding):
-        """Parse the template from an XML document."""
         streams = [[]] # stacked lists of events of the "compiled" template
         dirmap = {} # temporary mapping of directives to elements
         ns_prefix = {}