Include examples in documentation, and add tests for that

ZConfig/_schema_utils.py

@@ -13,11 +13,11 @@
 ##############################################################################
 from __future__ import print_function
 
-from abc import abstractmethod
 import argparse
 import itertools
 import sys
 import textwrap
+from abc import abstractmethod
 
 try:
     from itertools import ifilterfalse
@@ -279,6 +279,7 @@ def _visit_SectionInfo(self, name, info):
                     for sub in info.sectiontype:
                         self.visit(*sub)
 
+        self.fmt.example(info.example)
 
     @TypeVisitor(AbstractType)
     def _visit_AbstractType(self, name, info):

ZConfig/tests/input/simplesections.xml

@@ -14,7 +14,9 @@
     <key name="var" required="yes" />
   </sectiontype>
 
-  <multisection type="section" name="*" attribute="sections" />
+  <multisection type="section" name="*" attribute="sections">
+    <example>Multisection Example</example>
+  </multisection>
   <section type="minimal" name="*" attribute="minimal" />
   <section type="trivial" name="*" attribute="trivial" />
   <section type="hasmin" name="+" attribute="hasmin" />
@@ -48,6 +50,7 @@
   </sectiontype>
   <section type="abstype" name="absinfo">
 	  <description>Description</description>
+	  <example>Section Example</example>
   </section>
   <section type="extabs" name="extabs" />
   <section type="extabs" name="extabs2" />

ZConfig/tests/test_schema2html.py

@@ -19,12 +19,10 @@
 import unittest
 
 import docutils
-import docutils.utils
 import docutils.frontend
 import docutils.parsers.rst
 import docutils.parsers.rst.directives
-
-
+import docutils.utils
 
 try:
     # Note that we're purposely using the old
@@ -100,6 +98,20 @@ def test_cover_all_schemas(self):
             self.assertIn('</html>', res.getvalue())
             run_transform_rst(input_file(name))
 
+    def test_html_section_example(self):
+        name = 'simplesections.xml'
+        res = run_transform(input_file(name))
+        out = res.getvalue()
+        self.assertIn('Section Example', out)
+        self.assertIn('Multisection Example', out)
+
+    def test_rst_section_example(self):
+        name = 'simplesections.xml'
+        res = run_transform_rst(input_file(name))
+        out = res.getvalue()
+        self.assertIn('Section Example', out)
+        self.assertIn('Multisection Example', out)
+
     def test_cover_logging_components(self):
         res = run_transform('--package', 'ZConfig.components.logger')
         self.assertIn('eventlog', res.getvalue())