Add support for limiting the hierarchy, both in the directive and the…

… command line.

ZConfig/_schema_utils.py

@@ -15,10 +15,9 @@
 
 from abc import abstractmethod
 import argparse
-from contextlib import contextmanager
 import itertools
 import sys
-import cgi
+
 
 import ZConfig.loader
 
@@ -114,13 +113,23 @@ def body(self):
 class AbstractSchemaPrinter(AbstractBaseClass):
 
 
-    def __init__(self, schema, stream=None):
+    def __init__(self, schema, stream=None, allowed_names=()):
         self.schema = schema
         stream = stream or sys.stdout
         self._explained = set()
         self._seen_typenames = set()
         self.fmt = self._schema_formatter(schema, stream)
 
+        if allowed_names:
+            iter_all = self._iter_schema_items
+            allowed_names = {x.lower() for x in allowed_names}
+            def filtered():
+                for name, info in iter_all():
+                    if name and name.lower() in allowed_names:
+                        yield name, info
+
+            self._iter_schema_items = filtered
+
     @abstractmethod
     def _schema_formatter(self, schema, stream):
         "Return a formatter"

ZConfig/schema2html.py

@@ -103,6 +103,12 @@ def main(argv=None):
         default="component.xml",
         help="When PACKAGE is given, this can specify the file inside it to load.")
 
+    argparser.add_argument(
+        "--members",
+        action="store",
+        nargs="*",
+        help="Only output sections and types in this list (and reachable from it)")
+
     if RstSchemaPrinter:
         argparser.add_argument(
             "--format",
@@ -123,7 +129,7 @@ def main(argv=None):
         printer_factory = RstSchemaPrinter
 
 
-    printer_factory(schema, out).printSchema()
+    printer_factory(schema, out, allowed_names=args.members).printSchema()
 
 
     return 0

ZConfig/sphinx.py

@@ -162,12 +162,17 @@ class SchemaToRstDirective(Directive):
         optional_arguments = 1
         option_spec = {
             'file': str,
+            'members': str
         }
         def run(self):
             schema = load_schema(self.arguments[0],
                                  True, self.options.get('file'))
 
-            printer = RstSchemaPrinter(schema)
+            members = ()
+            if 'members' in self.options:
+                members = self.options['members'].split()
+
+            printer = RstSchemaPrinter(schema, allowed_names=members)
             printer.fmt.settings = self.state.document.settings
 
             printer.buildSchema()

ZConfig/tests/test_schema2html.py

@@ -144,6 +144,26 @@ def test_parse_package_file(self):
         # just that one file.
         self.assertNotIn("SMTPHandler", doc_text)
         self.assertIn("base-logger", doc_text)
+        self.assertIn("Base definition", doc_text)
+
+    def test_parse_package_limited_names(self):
+        text = """
+        Document
+        ========
+        .. zconfig:: ZConfig.components.logger
+            :members: syslog logfile
+        """
+        document = self._parse(text)
+        doc_text = document.astext()
+        print(doc_text)
+
+        # Check that it produced output, limited to
+        # just that one part of the tree
+        self.assertNotIn("SMTPHandler", doc_text)
+        self.assertIn("syslog", doc_text)
+        self.assertIn("SyslogHandlerFactory", doc_text)
+        self.assertIn("FileHandlerFactory", doc_text)
+
 
 
 def test_suite():

doc/using-zconfig.rst

@@ -250,5 +250,7 @@ For example, the value for ``key`` will evaluate to ``value``::
 Configuring Logging
 ===================
 
+Configuring handlers:
+
 .. zconfig:: ZConfig.components.logger
-    :file: component.xml
+    :members: ZConfig.logger.handler