better dedenting of description.

ZConfig/components/logger/base-logger.xml

@@ -16,7 +16,7 @@
         Verbosity setting for the logger.  Values must be a name of
         a level, or an integer in the range [0..50].  The names of the
         levels, in order of increasing verbosity (names on the same
-        line are equivalent):
+        line are equivalent)::
 
             critical, fatal
             error

ZConfig/sphinx.py

@@ -15,7 +15,7 @@
 
 
 from contextlib import contextmanager
-
+import textwrap
 
 try:
     from docutils import nodes
@@ -71,18 +71,14 @@ def description(self, text):
             if not text:
                 return
 
-            # Aggressively dedent the text to avoid producing unwanted
-            # definition lists.
-            # XXX: This is probably *too* aggressive.
-            texts = []
-            parts = text.split('\n')
-            for p in parts:
-                p = p.strip()
-                if not p:
-                    texts.append('\n')
-                else:
-                    texts.append(p)
-            text = '\n'.join(texts)
+            # dedent the text to avoid producing unwanted
+            # definition lists. The XML parser strips leading whitespace from
+            # the first line, but preserves it for subsequent lines, so for dedent
+            # to work we have to ignore that first line.
+            texts = text.split("\n")
+            if len(texts) > 1:
+                trail = textwrap.dedent('\n'.join(texts[1:]))
+                text = texts[0] + '\n' + trail
             self.write(self._parsed(text))
 
 

ZConfig/tests/test_schema2html.py

@@ -40,6 +40,7 @@
 
 from ZConfig.sphinx import SchemaToRstDirective
 docutils.parsers.rst.directives.register_directive("zconfig", SchemaToRstDirective)
+from ZConfig.sphinx import RstSchemaFormatter
 
 from .support import input_file
 from .support import with_stdin_from_input_file
@@ -164,6 +165,27 @@ def test_parse_package_limited_names(self):
         self.assertIn("FileHandlerFactory", doc_text)
 
 
+    def test_description_dedent(self):
+        text = """No leading whitespace on this line.
+        But this line has whitespace.
+        As does this one.
+        """
+        written = []
+        class FUT(RstSchemaFormatter):
+            def __init__(self):
+                pass
+            def _parsed(self, text):
+                return text
+            def write(self, *texts):
+                written.extend(texts)
+        fut = FUT()
+        fut.description(text)
+
+        dedented = ("""No leading whitespace on this line.\n"""
+        """But this line has whitespace.\n"""
+        """As does this one.\n""")
+
+        self.assertEqual(written[0], dedented)
 
 def test_suite():
     return unittest.defaultTestLoader.loadTestsFromName(__name__)

doc/using-zconfig.rst

@@ -253,4 +253,4 @@ Configuring Logging
 Configuring handlers:
 
 .. zconfig:: ZConfig.components.logger
-    :members: ZConfig.logger.handler
+    :members: ZConfig.logger.base-logger