Unify docs for xmlconfig.rst/py back into .pyissue40

3 files changed, 171 insertions, 224 deletions

diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst
index 73fb127..dd324db 100644
--- a/docs/api/exceptions.rst
+++ b/docs/api/exceptions.rst
@@ -1,6 +1,5 @@
-:mod:`zope.configuration.exceptions`
-====================================
+===============================
+ zope.configuration.exceptions
+===============================
 
-.. module:: zope.configuration.exceptions
-
-.. autoclass:: ConfigurationError
+.. automodule:: zope.configuration.exceptions
diff --git a/docs/api/xmlconfig.rst b/docs/api/xmlconfig.rst
index 63b94f5..a76b9c8 100644
--- a/docs/api/xmlconfig.rst
+++ b/docs/api/xmlconfig.rst
@@ -1,211 +1,5 @@
-:mod:`zope.configuration.xmlconfig`
-===================================
+==============================
+ zope.configuration.xmlconfig
+==============================
 
-.. module:: zope.configuration.xmlconfig
-
-.. autoclass:: ZopeXMLConfigurationError
-
-   Example
-
-   .. doctest::
-
-      >>> from zope.configuration.xmlconfig import ZopeXMLConfigurationError
-      >>> v = ZopeXMLConfigurationError("blah", AttributeError, "xxx")
-      >>> print(v)
-      'blah'
-          AttributeError: xxx
-
-.. autoclass:: ZopeSAXParseException
-
-   Example
-
-   .. doctest::
-
-      >>> from zope.configuration.xmlconfig import ZopeSAXParseException
-      >>> v = ZopeSAXParseException("foo.xml:12:3:Not well formed")
-      >>> print(v)
-      File "foo.xml", line 12.3, Not well formed
-
-.. autoclass:: ParserInfo
-   :members:
-   :member-order: bysource
-
-   Example
-
-   .. doctest::
-
-      >>> from zope.configuration.xmlconfig import ParserInfo
-      >>> info = ParserInfo('tests//sample.zcml', 1, 0)
-      >>> info
-      File "tests//sample.zcml", line 1.0
-
-      >>> print(info)
-      File "tests//sample.zcml", line 1.0
-
-      >>> info.characters("blah\\n")
-      >>> info.characters("blah")
-      >>> info.text
-      'blah\\nblah'
-
-      >>> info.end(7, 0)
-      >>> info
-      File "tests//sample.zcml", line 1.0-7.0
-
-      >>> print(info)
-      File "tests//sample.zcml", line 1.0-7.0
-        <configure xmlns='http://namespaces.zope.org/zope'>
-          <!-- zope.configure -->
-          <directives namespace="http://namespaces.zope.org/zope">
-            <directive name="hook" attributes="name implementation module"
-               handler="zope.configuration.metaconfigure.hook" />
-          </directives>
-        </configure>
-
-.. autoclass:: ConfigurationHandler
-
-   .. automethod:: evaluateCondition
-
-      The ``have`` and ``not-have`` verbs each take one argument: the name
-      of a feature:
-
-      .. doctest::
-
-         >>> from zope.configuration.config import ConfigurationContext
-         >>> from zope.configuration.xmlconfig import ConfigurationHandler
-         >>> context = ConfigurationContext()
-         >>> context.provideFeature('apidoc')
-         >>> c = ConfigurationHandler(context, testing=True)
-         >>> c.evaluateCondition("have apidoc")
-         True
-         >>> c.evaluateCondition("not-have apidoc")
-         False
-         >>> c.evaluateCondition("have onlinehelp")
-         False
-         >>> c.evaluateCondition("not-have onlinehelp")
-         True
-
-      Ill-formed expressions raise an error:
-
-      .. doctest::
-
-         >>> c.evaluateCondition("want apidoc")
-         Traceback (most recent call last):
-           ...
-         ValueError: Invalid ZCML condition: 'want apidoc'
-
-         >>> c.evaluateCondition("have x y")
-         Traceback (most recent call last):
-           ...
-         ValueError: Only one feature allowed: 'have x y'
-
-         >>> c.evaluateCondition("have")
-         Traceback (most recent call last):
-           ...
-         ValueError: Feature name missing: 'have'
-
-
-      The ``installed`` and ``not-installed`` verbs each take one argument:
-      the dotted name of a pacakge.
-
-      If the pacakge is found, in other words, can be imported,
-      then the condition will return true / false:
-
-      .. doctest::
-
-         >>> context = ConfigurationContext()
-         >>> c = ConfigurationHandler(context, testing=True)
-         >>> c.evaluateCondition('installed zope.interface')
-         True
-         >>> c.evaluateCondition('not-installed zope.interface')
-         False
-         >>> c.evaluateCondition('installed zope.foo')
-         False
-         >>> c.evaluateCondition('not-installed zope.foo')
-         True
-
-      Ill-formed expressions raise an error:
-
-      .. doctest::
-
-         >>> c.evaluateCondition("installed foo bar")
-         Traceback (most recent call last):
-           ...
-         ValueError: Only one package allowed: 'installed foo bar'
-
-         >>> c.evaluateCondition("installed")
-         Traceback (most recent call last):
-           ...
-         ValueError: Package name missing: 'installed'
-
-.. autofunction:: processxmlfile
-
-.. autofunction:: openInOrPlain
-
-   For example, the tests/samplepackage dirextory has files:
-
-   - configure.zcml
-   - configure.zcml.in
-   - foo.zcml.in
-
-   If we open configure.zcml, we'll get that file:
-
-   .. doctest::
-
-      >>> import os
-      >>> from zope.configuration.xmlconfig import __file__
-      >>> from zope.configuration.xmlconfig import openInOrPlain
-      >>> here = os.path.dirname(__file__)
-      >>> path = os.path.join(here, 'tests', 'samplepackage', 'configure.zcml')
-      >>> f = openInOrPlain(path)
-      >>> f.name[-14:]
-      'configure.zcml'
-      >>> f.close()
-
-   But if we open foo.zcml, we'll get foo.zcml.in, since there isn't a
-   foo.zcml:
-
-   .. doctest::
-
-      >>> path = os.path.join(here, 'tests', 'samplepackage', 'foo.zcml')
-      >>> f = openInOrPlain(path)
-      >>> f.name[-11:]
-      'foo.zcml.in'
-      >>> f.close()
-
-   Make sure other IOErrors are re-raised.  We need to do this in a
-   try-except block because different errors are raised on Windows and
-   on Linux.
-
-   .. doctest::
-
-      >>> try:
-      ...     f = openInOrPlain('.')
-      ... except IOError:
-      ...     print("passed")
-      ... else:
-      ...     print("failed")
-      passed
-
-.. autointerface:: IInclude
-   :members:
-   :member-order: bysource
-
-.. autofunction:: include
-
-.. autofunction:: exclude
-
-.. autofunction:: includeOverrides
-
-.. autofunction:: registerCommonDirectives
-
-.. autofunction:: file
-
-.. autofunction:: string
-
-.. autoclass:: XMLConfig
-   :members:
-   :member-order: bysource
-
-.. autofunction:: xmlconfig
-
-.. autofunction:: testxmlconfig
+.. automodule:: zope.configuration.xmlconfig
diff --git a/src/zope/configuration/xmlconfig.py b/src/zope/configuration/xmlconfig.py
index 18a2bbe..18f731f 100644
--- a/src/zope/configuration/xmlconfig.py
+++ b/src/zope/configuration/xmlconfig.py
@@ -71,10 +71,19 @@ ZCML_CONDITION = (ZCML_NAMESPACE, u"condition")
 
 
 class ZopeXMLConfigurationError(ConfigurationError):
-    """Zope XML Configuration error
+    """
+    Zope XML Configuration error
+
+    These errors are wrappers for other errors. They include
+    configuration info and the wrapped error type and value.
+
+    Example
 
-    These errors are wrappers for other errors. They include configuration
-    info and the wrapped error type and value.
+        >>> from zope.configuration.xmlconfig import ZopeXMLConfigurationError
+        >>> v = ZopeXMLConfigurationError("blah", AttributeError, "xxx")
+        >>> print(v)
+        'blah'
+            AttributeError: xxx
     """
     def __init__(self, info, etype, evalue):
         self.info, self.etype, self.evalue = info, etype, evalue
@@ -86,7 +95,15 @@ class ZopeXMLConfigurationError(ConfigurationError):
             repr(self.info), self.etype.__name__, self.evalue)
 
 class ZopeSAXParseException(ConfigurationError):
-    """Sax Parser errors, reformatted in an emacs friendly way
+    """
+    Sax Parser errors, reformatted in an emacs friendly way.
+
+    Example
+
+        >>> from zope.configuration.xmlconfig import ZopeSAXParseException
+        >>> v = ZopeSAXParseException("foo.xml:12:3:Not well formed")
+        >>> print(v)
+        File "foo.xml", line 12.3, Not well formed
     """
     def __init__(self, v):
         self._v = v
@@ -100,10 +117,40 @@ class ZopeSAXParseException(ConfigurationError):
             return str(v)
 
 class ParserInfo(object):
-    """Information about a directive based on parser data
+    """
+    Information about a directive based on parser data
 
     This includes the directive location, as well as text data
     contained in the directive.
+
+    Example
+
+        >>> from zope.configuration.xmlconfig import ParserInfo
+        >>> info = ParserInfo('tests//sample.zcml', 1, 0)
+        >>> info
+        File "tests//sample.zcml", line 1.0
+
+        >>> print(info)
+        File "tests//sample.zcml", line 1.0
+
+        >>> info.characters("blah\\n")
+        >>> info.characters("blah")
+        >>> info.text
+        'blah\\nblah'
+
+        >>> info.end(7, 0)
+        >>> info
+        File "tests//sample.zcml", line 1.0-7.0
+
+        >>> print(info)
+        File "tests//sample.zcml", line 1.0-7.0
+          <configure xmlns='http://namespaces.zope.org/zope'>
+            <!-- zope.configure -->
+            <directives namespace="http://namespaces.zope.org/zope">
+              <directive name="hook" attributes="name implementation module"
+                 handler="zope.configuration.metaconfigure.hook" />
+            </directives>
+          </configure>
     """
     text = u''
 
@@ -173,7 +220,8 @@ class ParserInfo(object):
 
 
 class ConfigurationHandler(ContentHandler):
-    """Interface to the xml parser
+    """
+    Interface to the xml parser
 
     Translate parser events into calls into the configuration system.
     """
@@ -231,12 +279,76 @@ class ConfigurationHandler(ContentHandler):
         self.context.setInfo(info)
 
     def evaluateCondition(self, expression):
-        """Evaluate a ZCML condition.
+        """
+        Evaluate a ZCML condition.
 
         ``expression`` is a string of the form "verb arguments".
 
         Currently the supported verbs are ``have``, ``not-have``,
         ``installed`` and ``not-installed``.
+
+        The ``have`` and ``not-have`` verbs each take one argument:
+        the name of a feature:
+
+            >>> from zope.configuration.config import ConfigurationContext
+            >>> from zope.configuration.xmlconfig import ConfigurationHandler
+            >>> context = ConfigurationContext()
+            >>> context.provideFeature('apidoc')
+            >>> c = ConfigurationHandler(context, testing=True)
+            >>> c.evaluateCondition("have apidoc")
+            True
+            >>> c.evaluateCondition("not-have apidoc")
+            False
+            >>> c.evaluateCondition("have onlinehelp")
+            False
+            >>> c.evaluateCondition("not-have onlinehelp")
+            True
+
+        Ill-formed expressions raise an error:
+
+            >>> c.evaluateCondition("want apidoc")
+            Traceback (most recent call last):
+              ...
+            ValueError: Invalid ZCML condition: 'want apidoc'
+
+            >>> c.evaluateCondition("have x y")
+            Traceback (most recent call last):
+              ...
+            ValueError: Only one feature allowed: 'have x y'
+
+            >>> c.evaluateCondition("have")
+            Traceback (most recent call last):
+              ...
+            ValueError: Feature name missing: 'have'
+
+        The ``installed`` and ``not-installed`` verbs each take one
+        argument: the dotted name of a pacakge.
+
+        If the pacakge is found, in other words, can be imported, then
+        the condition will return true / false:
+
+            >>> context = ConfigurationContext()
+            >>> c = ConfigurationHandler(context, testing=True)
+            >>> c.evaluateCondition('installed zope.interface')
+            True
+            >>> c.evaluateCondition('not-installed zope.interface')
+            False
+            >>> c.evaluateCondition('installed zope.foo')
+            False
+            >>> c.evaluateCondition('not-installed zope.foo')
+            True
+
+        Ill-formed expressions raise an error:
+
+            >>> c.evaluateCondition("installed foo bar")
+            Traceback (most recent call last):
+              ...
+            ValueError: Only one package allowed: 'installed foo bar'
+
+            >>> c.evaluateCondition("installed")
+            Traceback (most recent call last):
+              ...
+            ValueError: Package name missing: 'installed'
         """
         arguments = expression.split(None)
         verb = arguments.pop(0)
@@ -313,11 +425,53 @@ def processxmlfile(file, context, testing=False):
 
 
 def openInOrPlain(filename):
-    """Open a file, falling back to filename.in.
+    """
+    Open a file, falling back to filename.in.
 
     If the requested file does not exist and filename.in does, fall
-    back to filename.in.  If opening the original filename fails for
+    back to filename.in. If opening the original filename fails for
     any other reason, allow the failure to propogate.
+
+    For example, the tests/samplepackage dirextory has files:
+
+        - configure.zcml
+
+        - configure.zcml.in
+
+        - foo.zcml.in
+
+    If we open configure.zcml, we'll get that file:
+
+        >>> import os
+        >>> from zope.configuration.xmlconfig import __file__
+        >>> from zope.configuration.xmlconfig import openInOrPlain
+        >>> here = os.path.dirname(__file__)
+        >>> path = os.path.join(here, 'tests', 'samplepackage', 'configure.zcml')
+        >>> f = openInOrPlain(path)
+        >>> f.name[-14:]
+        'configure.zcml'
+        >>> f.close()
+
+    But if we open foo.zcml, we'll get foo.zcml.in, since there isn't
+    a foo.zcml:
+
+        >>> path = os.path.join(here, 'tests', 'samplepackage', 'foo.zcml')
+        >>> f = openInOrPlain(path)
+        >>> f.name[-11:]
+        'foo.zcml.in'
+        >>> f.close()
+
+    Make sure other IOErrors are re-raised. We need to do this in a
+    try-except block because different errors are raised on Windows
+    and on Linux.
+
+        >>> try:
+        ...     f = openInOrPlain('.')
+        ... except IOError:
+        ...     print("passed")
+        ... else:
+        ...     print("failed")
+        passed
     """
     try:
         return open(filename)