Support schemas in packages in the Sphinx extension.

Fixes #59

.travis.yml

@@ -1,17 +1,15 @@
 language: python
 sudo: false
+dist: xenial
 python:
     - 2.7
     - 3.4
     - 3.5
     - 3.6
+    - 3.7
     - pypy
     - pypy3
-matrix:
-    include:
-        - python: "3.7"
-          dist: xenial
-          sudo: true
+
 install:
     - pip install -U pip setuptools
     - pip install -U coverage coveralls

CHANGES.rst

@@ -1,15 +1,16 @@
-==========================
-Change History for ZConfig
-==========================
+============================
+ Change History for ZConfig
+============================
 
 3.4.1 (unreleased)
-------------------
-
-- TBD
+==================
 
+- Add support for documenting schema files contained in packages to
+  the Sphinx extension. See `issue 59
+  <https://github.com/zopefoundation/ZConfig/issues/59>`_.
 
 3.4.0 (2019-01-02)
-------------------
+==================
 
 Many changes have been made in the support for logging configurations:
 
@@ -54,7 +55,7 @@ Many changes have been made in the support for logging configurations:
 
 
 3.3.0 (2018-10-04)
-------------------
+==================
 
 - Drop support for Python 3.3.
 
@@ -72,7 +73,7 @@ Many changes have been made in the support for logging configurations:
   <https://github.com/zopefoundation/ZConfig/issues/37>`_.
 
 3.2.0 (2017-06-22)
-------------------
+==================
 
 - Drop support for Python 2.6 and 3.2 and add support for Python 3.6.
 
@@ -105,74 +106,74 @@ Many changes have been made in the support for logging configurations:
   https://github.com/zopefoundation/ZConfig/issues/17
 
 3.1.0 (2015-10-17)
-------------------
+==================
 
 - Add ability to do variable substitution from environment variables using
   $() syntax.
 
 3.0.4 (2014-03-20)
-------------------
+==================
 
 - Added Python 3.4 support.
 
 
 3.0.3 (2013-03-02)
-------------------
+==================
 
 - Added Python 3.2 support.
 
 
 3.0.2 (2013-02-14)
-------------------
+==================
 
 - Fixed ResourceWarning in BaseLoader.openResource().
 
 
 3.0.1 (2013-02-13)
-------------------
+==================
 
 - Removed an accidentally left `pdb` statement from the code.
 
 - Fix a bug in Python 3 with the custom string `repr()` function.
 
 
 3.0.0 (2013-02-13)
-------------------
+==================
 
 - Added Python 3.3 support.
 
 - Dropped Python 2.4 and 2.5 support.
 
 
 2.9.3 (2012-06-25)
-------------------
+==================
 
 - Fixed: port values of 0 weren't allowed.  Port 0 is used to request
   an ephemeral port.
 
 
 2.9.2 (2012-02-11)
-------------------
+==================
 
 - Adjust test classes to avoid base classes being considered separate
   test cases by (at least) the "nose" test runner.
 
 
 2.9.1 (2012-02-11)
-------------------
+==================
 
 - Make FileHandler.reopen thread safe.
 
 
 2.9.0 (2011-03-22)
-------------------
+==================
 
 - Allow identical redefinition of ``%define`` names.
 - Added support for IPv6 addresses.
 
 
 2.8.0 (2010-04-13)
-------------------
+==================
 
 - Fix relative path recognition.
   https://bugs.launchpad.net/zconfig/+bug/405687
@@ -181,15 +182,15 @@ Many changes have been made in the support for logging configurations:
 
 
 2.7.1 (2009-06-13)
-------------------
+==================
 
 - Improved documentation
 
 - Fixed tests failures on windows.
 
 
 2.7.0 (2009-06-11)
-------------------
+==================
 
 - Added a convenience function, ``ZConfig.configureLoggers(text)`` for
   configuring loggers.
@@ -200,7 +201,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.6.1 (2008-12-05)
-------------------
+==================
 
 - Fixed support for schema descriptions that override descriptions from a base
   schema.  If multiple base schema provide descriptions but the derived schema
@@ -213,7 +214,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.6.0 (2008-09-03)
-------------------
+==================
 
 - Added support for file rotation by time by specifying when and
   interval, rather than max-size, for log files.
@@ -222,7 +223,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.5.1 (2007-12-24)
-------------------
+==================
 
 - Made it possible to run unit tests via 'python setup.py test' (requires
   setuptools on sys.path).
@@ -231,7 +232,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.5 (2007-08-31)
-------------------------
+================
 
 *A note on the version number:*
 
@@ -268,14 +269,14 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.3.1 (2005-08-21)
-------------------
+==================
 
 - Isolated some of the case-normalization code so it will at least be
   easier to override.  This remains non-trivial.
 
 
 2.3 (2005-05-18)
-----------------
+================
 
 - Added "inet-binding-address" and "inet-connection-address" to the
   set of standard datatypes.  These are similar to the "inet-address"
@@ -290,7 +291,7 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.2 (2004-04-21)
-----------------
+================
 
 - More documentation has been written.
 
@@ -318,7 +319,7 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.1 (2004-04-12)
-----------------
+================
 
 - Removed compatibility with Python 2.1 and 2.2.
 
@@ -354,7 +355,7 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.0 (2003-10-27)
-----------------
+================
 
 - Configurations can import additional schema components using a new
   "%import" directive; this can be used to integrate 3rd-party
@@ -371,6 +372,6 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 1.0 (2003-03-25)
-----------------
+================
 
 - Initial release.

ZConfig/_schema_utils.py

@@ -308,15 +308,38 @@ def _visit_default(self, name, info):
     del TypeVisitor
 
 
-def load_schema(schema, package, package_file):
+def load_schema(schema,
+                package=False,
+                package_file='component.xml',
+                component=True):
+    """
+    Load the *schema* and return the schema object.
+
+    By default, *schema* is interpreted as a path on disk to a schema
+    file.
+
+    If *package* is set to True, then *schema* must name a Python
+    package, and the file will be loaded from that package, defaulting
+    to the ``component.xml`` file as nemed by *package_file*. In this
+    case, a ``<schema>`` is generated that imports this component.
+
+    If *package* is set to True and *component* is set to False, then
+    no schema tag is added and the file must refer to an actual
+    schema.
+    """
+
     if not package:
+        # A schema file
         schema_reader = argparse.FileType('r')(schema)
-    else:
+        return ZConfig.loader.loadSchemaFile(schema_reader)
+
+    if component:
+        # A component in a package
         schema_template = (
             "<schema><import package='%s' file='%s' /></schema>"
-            % (schema, package_file or 'component.xml'))
+            % (schema, package_file))
         from ZConfig._compat import TextIO
-        schema_reader = TextIO(schema_template)
+        return ZConfig.loader.loadSchemaFile(TextIO(schema_template))
 
-    schema = ZConfig.loader.loadSchemaFile(schema_reader)
-    return schema
+    # A schema in a package
+    return ZConfig.loader.loadSchema('package:%s:%s' % (schema, package_file))

ZConfig/sphinx.py

@@ -149,16 +149,21 @@ def printSchema(self):
 
     class SchemaToRstDirective(Directive):
         required_arguments = 1
-        optional_arguments = 2
+        optional_arguments = 4
         option_spec = {
             'file': str,
             'members': str,
             'excluded-members': str,
+            'schema': bool,
         }
 
         def run(self):
-            schema = load_schema(self.arguments[0],
-                                 True, self.options.get('file'))
+            schema = load_schema(
+                self.arguments[0],
+                package=True,
+                package_file=self.options.get('file', 'component.xml'),
+                component=not self.options.get('schema')
+            )
 
             members = ()
             if 'members' in self.options:

ZConfig/tests/sphinx_test_schema.xml

@@ -0,0 +1,26 @@
+<schema>
+
+  <!--
+      This is for testing the support of schemas in our Sphinx
+      extension.
+  -->
+
+
+  <description>
+    This describes the schema.
+  </description>
+
+
+  <import package="ZConfig.components.logger" file="abstract.xml"/>
+  <import package="ZConfig.components.logger" file="base-logger.xml"/>
+
+  <sectiontype name="eventlog"
+               datatype="ZConfig.components.logger.logger.EventLogFactory"
+               extends="ZConfig.logger.base-logger"
+               implements="ZConfig.logger.log">
+    <description>
+      Configuration for the root logger.
+    </description>
+  </sectiontype>
+
+</schema>

ZConfig/tests/test_schema2html.py

@@ -197,6 +197,21 @@ def test_parse_package_excluded_names(self):
         self.assertNotIn("SyslogHandlerFactory", doc_text)
         self.assertNotIn("FileHandlerFactory", doc_text)
 
+    def test_parse_package_schema(self):
+        text = """
+        Document
+        ========
+        .. zconfig:: ZConfig.tests
+            :file: sphinx_test_schema.xml
+            :schema: true
+        """
+        document = self._parse(text)
+        doc_text = document.astext()
+
+        # Check that it produced output
+        self.assertIn("EventLogFactory", doc_text)
+        self.assertIn("<eventlog>", doc_text)
+
     def test_description_dedent(self):
         text = """No leading whitespace on this line.
         But this line has whitespace.

doc/documenting-components.rst

@@ -5,10 +5,10 @@
  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:
+ZConfig includes a docutils directive for documenting components and
+schemas 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
 
@@ -28,7 +28,8 @@ There is one directive:
 
    By default, the contents of ``component.xml`` will be documented.
    You can specify the ``:file:`` option to choose a different file
-   from that package.
+   from that package. If you wish to document a schema instead of a
+   set of components, add the option ``:schema: true``.
 
    Each component will have its name, type, and default value
    documented. The description of the component will be rendered as