Merge pull request #25 from zopefoundation/issue8

 Flesh out the docs for ``includeOverrides`` a little bit

4 files changed, 77 insertions, 81 deletions

diff --git a/docs/conf.py b/docs/conf.py
index f74063b..9fffd20 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,7 +11,11 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+import pkg_resources
+sys.path.append(os.path.abspath('../src'))
+rqmt = pkg_resources.require('zope.configuration')[0]
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -28,6 +32,7 @@ import sys, os
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'repoze.sphinx.autointerface',
@@ -54,9 +59,9 @@ copyright = u'2012, Zope Foundation Contributors'
 # built documents.
 #
 # The short X.Y version.
-version = '4.0'
+version = '%s.%s' % tuple(map(int, rqmt.version.split('.')[:2]))
 # The full version, including alpha/beta/rc tags.
-release = '4.0'
+release = rqmt.version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -73,7 +78,7 @@ release = '4.0'
 exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
+default_role = 'obj'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
@@ -246,3 +251,12 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+intersphinx_mapping = {
+    'https://docs.python.org/': None,
+    'https://zopeschema.readthedocs.io/en/latest': None,
+}
+
+autodoc_default_flags = ['members', 'show-inheritance']
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'
diff --git a/docs/narr.rst b/docs/narr.rst
index ffd317b..b7d93b4 100644
--- a/docs/narr.rst
+++ b/docs/narr.rst
@@ -685,7 +685,7 @@ Now, we'll include the zope.configuration.tests.excludedemo config:
    >>> _ = string('<include package="zope.configuration.tests.excludedemo" />')
    >>> len(handler.buffer)
    3
-   >>> logged = [x.msg for x in handler.buffer]
+   >>> logged = [x.getMessage() for x in handler.buffer]
    >>> logged[0].startswith('include ')
    True
    >>> logged[0].endswith('zope/configuration/tests/excludedemo/configure.zcml')
@@ -708,7 +708,7 @@ rerunning gives the same thing:
    >>> _ = string('<include package="zope.configuration.tests.excludedemo" />')
    >>> len(handler.buffer)
    3
-   >>> logged = [x.msg for x in handler.buffer]
+   >>> logged = [x.getMessage() for x in handler.buffer]
    >>> logged[0].startswith('include ')
    True
    >>> logged[0].endswith('zope/configuration/tests/excludedemo/configure.zcml')
@@ -738,7 +738,7 @@ by the configuration file in zope.configuration.tests.excludedemo:
    ... ''')
    >>> len(handler.buffer)
    1
-   >>> logged = [x.msg for x in handler.buffer]
+   >>> logged = [x.getMessage() for x in handler.buffer]
    >>> logged[0].startswith('include ')
    True
    >>> logged[0].endswith('zope/configuration/tests/excludedemo/configure.zcml')
diff --git a/src/zope/configuration/tests/test_xmlconfig.py b/src/zope/configuration/tests/test_xmlconfig.py
index 66c9341..d59bae9 100644
--- a/src/zope/configuration/tests/test_xmlconfig.py
+++ b/src/zope/configuration/tests/test_xmlconfig.py
@@ -487,7 +487,7 @@ class Test_include(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             self._callFUT(context)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn,), {}))
         self.assertEqual(len(context.actions), 1)
         action = context.actions[0]
         self.assertEqual(action['callable'], foo.data.append)
@@ -511,7 +511,7 @@ class Test_include(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             self._callFUT(context, 'simple.zcml')
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn,), {}))
         self.assertEqual(len(context.actions), 3)
         action = context.actions[0]
         self.assertEqual(action['callable'], simple.file_registry.append)
@@ -549,9 +549,9 @@ class Test_include(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             self._callFUT(context, package=samplepackage, files='baz*.zcml')
         self.assertEqual(len(logger.debugs), 3)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn1, (), {}))
-        self.assertEqual(logger.debugs[1], ('include %s' % fqn2, (), {}))
-        self.assertEqual(logger.debugs[2], ('include %s' % fqn3, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn1,), {}))
+        self.assertEqual(logger.debugs[1], ('include %s', (fqn2,), {}))
+        self.assertEqual(logger.debugs[2], ('include %s', (fqn3,), {}))
         self.assertEqual(len(context.actions), 2)
         action = context.actions[0]
         self.assertEqual(action['callable'], foo.data.append)
@@ -665,7 +665,7 @@ class Test_includeOverrides(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             self._callFUT(context, 'simple.zcml')
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn,), {}))
         self.assertEqual(len(context.actions), 4)
         action = context.actions[0]
         self.assertEqual(action['discriminator'], None)
@@ -705,7 +705,7 @@ class Test_file(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             context = self._callFUT(file_name, execute=False)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % file_name, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (file_name,), {}))
         self.assertEqual(len(foo.data), 0)
         self.assertEqual(len(context.actions), 1)
         action = context.actions[0]
@@ -724,7 +724,7 @@ class Test_file(unittest.TestCase):
             context = self._callFUT('configure.zcml', package=samplepackage,
                                     execute=False)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % file_name, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (file_name,), {}))
         self.assertEqual(len(foo.data), 0)
         self.assertTrue(context.package is samplepackage)
         self.assertEqual(len(context.actions), 1)
@@ -750,7 +750,7 @@ class Test_file(unittest.TestCase):
                                 execute=False)
         self.assertTrue(ret is context)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % file_name, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (file_name,), {}))
         self.assertEqual(len(foo.data), 0)
         self.assertEqual(len(context.actions), 1)
         action = context.actions[0]
@@ -768,7 +768,7 @@ class Test_file(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             context = self._callFUT(file_name)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % file_name, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (file_name,), {}))
         data = foo.data.pop()
         self.assertEqual(data.args, (('x', b('blah')), ('y', 0)))
         self.assertTrue(
@@ -873,7 +873,7 @@ class XMLConfigTests(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             xc = self._makeOne(path)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % path, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (path,), {}))
         self.assertEqual(len(foo.data), 0) # no execut_actions
         self.assertEqual(len(xc.context.actions), 1)
         action = xc.context.actions[0]
@@ -891,7 +891,7 @@ class XMLConfigTests(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             xc = self._makeOne(fqn)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn,), {}))
         self.assertEqual(len(foo.data), 0) # no execut_actions
         self.assertEqual(len(xc.context.actions), 1)
         action = xc.context.actions[0]
@@ -909,7 +909,7 @@ class XMLConfigTests(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             xc = self._makeOne("configure.zcml", samplepackage)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn,), {}))
         self.assertEqual(len(foo.data), 0) # no execut_actions
         self.assertEqual(len(xc.context.actions), 1)
         action = xc.context.actions[0]
@@ -928,7 +928,7 @@ class XMLConfigTests(unittest.TestCase):
         with _Monkey(xmlconfig, logger=logger):
             xc = self._makeOne(fqn)
         self.assertEqual(len(logger.debugs), 1)
-        self.assertEqual(logger.debugs[0], ('include %s' % fqn, (), {}))
+        self.assertEqual(logger.debugs[0], ('include %s', (fqn,), {}))
         self.assertEqual(len(foo.data), 0)
         xc() # call to process the actions
         self.assertEqual(len(foo.data), 1)
@@ -1184,22 +1184,3 @@ class LoggerStub(object):
 
     def debug(self, msg, *args, **kwargs):
         self.debugs.append((msg, args, kwargs))
-
-
-def test_suite():
-    return unittest.TestSuite((
-        unittest.makeSuite(ZopeXMLConfigurationErrorTests),
-        unittest.makeSuite(ZopeSAXParseExceptionTests),
-        unittest.makeSuite(ParserInfoTests),
-        unittest.makeSuite(ConfigurationHandlerTests),
-        unittest.makeSuite(Test_processxmlfile),
-        unittest.makeSuite(Test_openInOrPlain),
-        unittest.makeSuite(Test_include),
-        unittest.makeSuite(Test_exclude),
-        unittest.makeSuite(Test_includeOverrides),
-        unittest.makeSuite(Test_file),
-        unittest.makeSuite(Test_string),
-        unittest.makeSuite(XMLConfigTests),
-        unittest.makeSuite(Test_xmlconfig),
-        unittest.makeSuite(Test_testxmlconfig),
-    ))
diff --git a/src/zope/configuration/xmlconfig.py b/src/zope/configuration/xmlconfig.py
index 930c1fc..55d1aee 100644
--- a/src/zope/configuration/xmlconfig.py
+++ b/src/zope/configuration/xmlconfig.py
@@ -44,12 +44,11 @@ from zope.configuration.zopeconfigure import IZopeConfigure
 from zope.configuration.zopeconfigure import ZopeConfigure
 from zope.configuration._compat import StringIO
 from zope.configuration._compat import reraise
-from zope.configuration._compat import u
 
 logger = logging.getLogger("config")
 
 ZCML_NAMESPACE = "http://namespaces.zope.org/zcml"
-ZCML_CONDITION = (ZCML_NAMESPACE, u("condition"))
+ZCML_CONDITION = (ZCML_NAMESPACE, u"condition")
 
 
 class ZopeXMLConfigurationError(ConfigurationError):
@@ -87,7 +86,7 @@ class ParserInfo(object):
     This includes the directive location, as well as text data
     contained in the directive.
     """
-    text = u('')
+    text = u''
 
     def __init__(self, file, line, column):
         self.file, self.line, self.column = file, line, column
@@ -122,31 +121,31 @@ class ParserInfo(object):
             src = "  Could not read source."
         else:
             ecolumn = self.ecolumn
-            if lines[-1][ecolumn:ecolumn+2] == '</': #pragma NO COVER
+            if lines[-1][ecolumn:ecolumn+2] == '</': # pragma: no cover
                 # We're pointing to the start of an end tag. Try to find
                 # the end
                 l = lines[-1].find('>', ecolumn)
                 if l >= 0:
                     lines[-1] = lines[-1][:l+1]
-            else: #pragma NO COVER
+            else: # pragma: no cover
                 lines[-1] = lines[-1][:ecolumn+1]
 
             column = self.column
-            if lines[0][:column].strip(): #pragma NO COVER
+            if lines[0][:column].strip(): # pragma: no cover
                 # Remove text before start if it's noy whitespace
                 lines[0] = lines[0][self.column:]
 
-            pad = u('  ')
-            blank = u('')
+            pad = u'  '
+            blank = u''
             try:
                 src = blank.join([pad + l for l in lines])
-            except UnicodeDecodeError: #pragma NO COVER
+            except UnicodeDecodeError: # pragma: no cover
                 # XXX:
                 # I hope so most internation zcml will use UTF-8 as encoding
                 # otherwise this code must be made more clever
                 src = blank.join([pad + l.decode('utf-8') for l in lines])
                 # unicode won't be printable, at least on my console
-                src = src.encode('ascii','replace')
+                src = src.encode('ascii', 'replace')
 
         return "%s\n%s" % (repr(self), src)
 
@@ -202,7 +201,7 @@ class ConfigurationHandler(ContentHandler):
 
         try:
             self.context.begin(name, data, info)
-        except (KeyboardInterrupt, SystemExit): #pragma NO COVER
+        except (KeyboardInterrupt, SystemExit): # pragma: no cover
             raise
         except:
             if self.testing:
@@ -270,7 +269,7 @@ class ConfigurationHandler(ContentHandler):
 
         try:
             self.context.end()
-        except (KeyboardInterrupt, SystemExit): #pragma NO COVER
+        except (KeyboardInterrupt, SystemExit): # pragma: no cover
             raise
         except:
             if self.testing:
@@ -317,24 +316,25 @@ def openInOrPlain(filename):
 
 
 class IInclude(Interface):
-    """The ``include``, ``includeOverrides`` and ``exclude`` directives
+    """The `include`, `includeOverrides` and `exclude`
+    directives.
 
-    These directives allows you to include or preserve including of another
-    ZCML file in the configuration. This enables you to write configuration
-    files in each package and then link them together.
+    These directives allows you to include or preserve including of
+    another ZCML file in the configuration. This enables you to write
+    configuration files in each package and then link them together.
     """
 
     file = NativeStringLine(
-        title=u("Configuration file name"),
-        description=u("The name of a configuration file to be included/"
-                      "excluded, relative to the directive containing the "
-                      "including configuration file."),
+        title=u"Configuration file name",
+        description=(u"The name of a configuration file to be included/"
+                     u"excluded, relative to the directive containing the "
+                     u"including configuration file."),
         required=False,
-        )
+    )
 
     files = NativeStringLine(
-        title=u("Configuration file name pattern"),
-        description=u("""
+        title=u"Configuration file name pattern",
+        description=u"""
         The names of multiple configuration files to be included/excluded,
         expressed as a file-name pattern, relative to the directive
         containing the including or excluding configuration file.
@@ -350,24 +350,22 @@ class IInclude(Interface):
 
         The file names are included in sorted order, where sorting is
         without regard to case.
-        """),
+        """,
         required=False,
-        )
+    )
 
     package = GlobalObject(
-        title=u("Include or exclude package"),
-        description=u("""
+        title=u"Include or exclude package",
+        description=u"""
         Include or exclude the named file (or configure.zcml) from the
         directory of this package.
-        """),
+        """,
         required=False,
-        )
+    )
 
 
 def include(_context, file=None, package=None, files=None):
     """Include a zcml file
-
-    See examples in tests/text_xmlconfig.py
     """
 
     if files:
@@ -393,7 +391,7 @@ def include(_context, file=None, package=None, files=None):
     for path in paths:
         if context.processFile(path):
             with openInOrPlain(path) as f:
-                logger.debug("include %s" % f.name)
+                logger.debug("include %s", f.name)
 
                 context.basepath = os.path.dirname(path)
                 context.includepath = _context.includepath + (f.name, )
@@ -405,7 +403,7 @@ def include(_context, file=None, package=None, files=None):
 
 def exclude(_context, file=None, package=None, files=None):
     """Exclude a zcml file
-    
+
     This directive should be used before any ZML that includes
     configuration you want to exclude.
     """
@@ -437,13 +435,17 @@ def exclude(_context, file=None, package=None, files=None):
         context.processFile(path)
 
 def includeOverrides(_context, file=None, package=None, files=None):
-    """Include zcml file containing overrides
+    """Include zcml file containing overrides.
 
-    The actions in the included file are added to the context as if they
-    were in the including file directly.
+    The actions in the included file are added to the context as if
+    they were in the including file directly. Conflicting actions
+    added by the named *file* or *files* are resolved before this
+    directive completes.
 
-    See the detailed example in test_includeOverrides in
-    tests/text_xmlconfig.py
+    .. caution::
+        If you do not specify a *file*, then the default file
+        of ``configure.zcml`` will be used. A common use is to set *file*
+        to ``overrides.zcml``.
     """
 
     # We need to remember how many actions we had before
@@ -534,9 +536,9 @@ def _getContext():
         _clearContext()
         try:
             from zope.testing.cleanup import addCleanUp
-        except ImportError: #pragma NO COVER
+        except ImportError: # pragma: no cover
             pass
-        else: #pragma NO COVER
+        else: # pragma: no cover
             addCleanUp(_clearContext)
             del addCleanUp
     return _context
@@ -569,4 +571,3 @@ def testxmlconfig(file):
     context = _getContext()
     processxmlfile(file, context, testing=True)
     context.execute_actions(testing=True)
-