Add doc for zconfig directive.

CHANGES.rst

@@ -20,6 +20,10 @@ Change History for ZConfig
 - Scripts ``zconfig`` (for schema validation) and
   ``zconfig_schema2html`` are ported to Python 3.
 
+- A new ``ZConfig.sphinx`` Sphinx extension facilitates automatically
+  documenting ZConfig components using their description and examples
+  in Sphinx documentation.
+
 3.1.0 (2015-10-17)
 ------------------
 

ZConfig/_schema_utils.py

@@ -35,6 +35,7 @@
 from ZConfig.info import SectionType
 from ZConfig.info import SectionInfo
 from ZConfig.info import ValueInfo
+from ZConfig.info import MultiKeyInfo
 from ZConfig.info import AbstractType
 
 
@@ -290,7 +291,10 @@ def _visit_default(self, name, info):
         if isinstance(default, ValueInfo):
             default = default.value
 
-        self.fmt.describing_name(info.name, info.description, info.datatype,
+        name = info.name
+        if isinstance(info, MultiKeyInfo):
+            name = name + " (*)"
+        self.fmt.describing_name(name, info.description, info.datatype,
                                  default=default, metadefault=info.metadefault)
 
     del TypeVisitor

ZConfig/components/logger/handlers.xml

@@ -82,6 +82,17 @@
                datatype=".SMTPHandlerFactory"
                implements="ZConfig.logger.handler"
                extends="ZConfig.logger.base-log-handler">
+    <example><![CDATA[
+      <email-notifier>
+        to sysadmin@example.com
+        to john@example.com
+        from zlog-user@example.com
+        level fatal
+        smtp-username john
+        smtp-password johnpw
+      </email-notifier>
+    ]]>
+    </example>
     <key name="from" required="yes" attribute="fromaddr"/>
     <multikey name="to" required="yes" attribute="toaddrs"/>
     <key name="subject" default="Message from Zope"/>

doc/developing-with-zconfig.rst

@@ -10,3 +10,4 @@
    standard-datatypes
    standard-components
    writing-components
+   documenting-components

doc/documenting-components.rst

@@ -0,0 +1,69 @@
+
+.. _documenting-components:
+
+========================
+ Documenting Components
+========================
+
+ZConfig includes a docutils directive for documenting components that
+you create. This directive can function as a Sphinx extension if you
+include ``ZConfig.sphinx`` in the ``extensions`` value of your Sphinx
+configuration:
+
+.. code-block:: python
+
+  extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.interpsphinx',
+    'ZConfig.sphinx',
+  ]
+
+There is one directive:
+
+.. rst:directive:: .. zconfig:: <package-name>
+
+   .. versionadded:: 3.2.0
+
+   Document the components found in the Python package *package-name*.
+
+   By default, the contents of ``component.xml`` will be documented.
+   You can specify the ``:file:`` option to choose a different file
+   from that package.
+
+   Each component will have its name, type, and default value
+   documented. The description of the component will be rendered as
+   reStructuredText (and so can use directives like ``py:class:`` and
+   ``py:meth:`` to perform cross references). Any example for the
+   component will be rendered as a pre-formatted block.
+
+   All ZConfig components reachable will be documented, in the order
+   in which they are found. Often times, if your component extends
+   other components, this will produce too much documentation (it will
+   document the components you are extending in addition to the unique
+   aspects of your component). You can use the ``:members:`` and
+   ``:excluded-members:`` options to limit this.
+
+   Both of these options take a space-separated list of component
+   names. These options can be used together. When ``:members:`` is
+   given, only items that are explicitly named, or that are reachable
+   from such items, are documented. The ``:excluded-members:`` option
+   overrides this, causing any such members to be explicitly excluded.
+
+   These options are also useful for breaking the description of a
+   component up into multiple distinct sections, with narrative
+   documentation between them. For example, to document the main
+   logger component provided by ZConfig separately from each type of
+   handler ZConfig provides, the document might look like this:
+
+.. code-block:: rst
+
+   You can configure a logger and logging level with ZConfig:
+
+   .. zconfig:: ZConfig.components.logger
+       :members: ZConfig.logger.base-logger
+       :excluded-members: zconfig.logger.handler
+
+   ZConfig supports multiple different types of handlers for a given logger:
+
+   .. zconfig:: ZConfig.components.logger
+       :members: zconfig.logger.handler

doc/standard-components.rst

@@ -270,19 +270,11 @@ Configuring the email logger
 ----------------------------
 
 ZConfig has support for Python's :class:`logging.handlers.SMTPHandler`
-via the ``<email-notifier>`` handler::
+via the ``<email-notifier>`` handler.
 
-
-  <eventlog>
-    <email-notifier>
-      to sysadmin@example.com
-      to john@example.com
-      from zlog-user@example.com
-      level fatal
-      smtp-username john
-      smtp-password johnpw
-    </email-notifier>
-  </eventlog>
+.. zconfig:: ZConfig.components.logger
+     :file: handlers.xml
+     :members: email-notifier
 
 
 For details about the :class:`~logging.handlers.SMTPHandler` see the

doc/tools.rst

@@ -19,6 +19,9 @@ Documenting Schemas
 ===================
 
 ZConfig also installs a tool called ``zconfig_schema2html`` that can
-print schemas in a simple HTML format:
+print schemas in a simple HTML format.
 
-  .. program-output:: zconfig_schema2html --help
+.. hint:: To document components in reStructuredText, e.g., with
+		 Sphinx, see :ref:`documenting-components`.
+
+.. program-output:: zconfig_schema2html --help

doc/using-zconfig.rst

@@ -246,17 +246,3 @@ For example, the value for ``key`` will evaluate to ``value``::
 
   %define name value
   key $name
-
-Configuring Logging
-===================
-
-Configuring loggers:
-
-.. zconfig:: ZConfig.components.logger
-    :members: ZConfig.logger.base-logger
-    :excluded-members: zconfig.logger.handler
-
-Configuring handlers:
-
-.. zconfig:: ZConfig.components.logger
-    :members: zconfig.logger.handler

doc/writing-components.rst

@@ -41,7 +41,7 @@ Python class.
 
 The example component we build here will be in the :mod:`noise`
 package, but any package will do.  Components loadable using
-``%import`` must be contained in the 'component.xml' file;
+``%import`` must be contained in the ``component.xml`` file;
 alternate filenames may not be selected by the ``%import``
 construct.