[Zope3-checkins] SVN: Zope3/trunk/ Added new `apidoc:rotModule` directive, so that third-party products can

Stephan Richter srichter at cosmos.phy.tufts.edu
Sat Sep 11 18:24:02 EDT 2004


Log message for revision 27499:
  Added new `apidoc:rotModule` directive, so that third-party products can 
  easily add their package to the class browser documentation.
  


Changed:
  U   Zope3/trunk/doc/CHANGES.txt
  U   Zope3/trunk/src/bugtracker/configure.zcml
  U   Zope3/trunk/src/zope/app/apidoc/classmodule/__init__.py
  U   Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py
  U   Zope3/trunk/src/zope/app/apidoc/classmodule/configure.zcml
  A   Zope3/trunk/src/zope/app/apidoc/classmodule/meta.zcml
  A   Zope3/trunk/src/zope/app/apidoc/classmodule/metaconfigure.py
  A   Zope3/trunk/src/zope/app/apidoc/classmodule/metadirectives.py
  U   Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py
  U   Zope3/trunk/src/zwiki/configure.zcml


-=-
Modified: Zope3/trunk/doc/CHANGES.txt
===================================================================
--- Zope3/trunk/doc/CHANGES.txt	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/doc/CHANGES.txt	2004-09-11 22:24:02 UTC (rev 27499)
@@ -10,6 +10,9 @@
 
     New features
 
+      - Added `apidoc:rootModule` directive, so that third-party products can
+        add their packages to the class browser documentation module.
+
       - Separated the trusted and untrusted behaviors of page
         templates in the application server.  File-system-based
         templates are trusted, and database-based templates are

Modified: Zope3/trunk/src/bugtracker/configure.zcml
===================================================================
--- Zope3/trunk/src/bugtracker/configure.zcml	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/bugtracker/configure.zcml	2004-09-11 22:24:02 UTC (rev 27499)
@@ -386,8 +386,6 @@
   <i18n:registerTranslations directory="locales" />
 
   <!-- Register application with API Doc Tool -->
-  <!--
   <apidoc:rootModule module="bugtracker" />
-  -->
 
 </configure>

Modified: Zope3/trunk/src/zope/app/apidoc/classmodule/__init__.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/__init__.py	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/__init__.py	2004-09-11 22:24:02 UTC (rev 27499)
@@ -28,9 +28,10 @@
 import zope
 from zope.security.checker import getCheckerForInstancesOf
 from zope.interface import Interface, Attribute, implements, implementedBy
+
+from zope.app import zapi
 from zope.app.container.interfaces import IReadContainer
 from zope.app.i18n import ZopeMessageIDFactory as _
-
 from zope.app.location.interfaces import ILocation
 from zope.app.apidoc.interfaces import IDocumentationModule
 from zope.app.apidoc.utilities import ReadContainerBase
@@ -46,6 +47,14 @@
 IGNORE_FILES = ('tests', 'tests.py', 'ftests', 'ftests.py', 'CVS', 'gadfly',
                 'setup.py', 'introspection.py', 'Mount.py')
 
+class IAPIDocRootModule(Interface):
+    """Marker interface for utilities that represent class browser root
+    modules.
+
+    The utilities will be simple strings, representing the modules Python
+    dotted name.
+    """ 
+
 class IModuleDocumentation(IReadContainer):
     """Representation of a Python module for documentation.
 
@@ -558,7 +567,7 @@
 
       >>> names = cm.keys()
       >>> names.sort()
-      >>> names == cm.rootModules
+      >>> names == [u'zope']
       True
     """
     implements(IDocumentationModule)
@@ -588,8 +597,6 @@
     interface that requires a method or attribute to be implemented and the
     permissions required to access it.
     """)
-    rootModules = ['ZConfig', 'ZODB', 'transaction', 'zdaemon', 'zope']
-
     def __init__(self):
         """Initialize object."""
         super(ClassModule, self).__init__(None, '', None, False)
@@ -597,8 +604,8 @@
 
     def __setup(self):
         """Setup module and class tree."""
-        for name in self.rootModules:
-            self._Module__children[name] = Module(self, name, safe_import(name))
+        for name, mod in zapi.getUtilitiesFor(IAPIDocRootModule):
+            self._Module__children[name] = Module(self, name, safe_import(mod))
 
     def getDocString(self):
         """See Module class."""

Modified: Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/browser.py	2004-09-11 22:24:02 UTC (rev 27499)
@@ -92,7 +92,7 @@
            [('path', 'zope.app.apidoc.classmodule.browser.Foo2'),
             ('url',
              'http://127.0.0.1/zope/app/apidoc/classmodule/browser/Foo2')]]
-
+          
           >>> menu.request = TestRequest(form={'path': 'o2'})
           >>> info = menu.findClasses()
           >>> pprint(info)
@@ -537,7 +537,7 @@
           >>> from tests import getClassDetailsView
           >>> view = getClassDetailsView()
 
-          >>> attr = view.getAttributes()[2]
+          >>> attr = view.getAttributes()[1]
           >>> pprint(attr)
           [('interface', 'zope.app.apidoc.interfaces.IDocumentationModule'),
            ('name', 'title'),
@@ -668,8 +668,8 @@
           >>> view = getModuleDetailsView()
 
           >>> entries = view.getEntries(False)
-          >>> entries.sort()
-          >>> pprint(entries[1:3])
+          >>> entries.sort(lambda x, y: cmp(x['name'], y['name']))
+          >>> pprint(entries[6:8])
           [[('isclass', False),
             ('isfunction', False),
             ('ismodule', True),
@@ -710,7 +710,7 @@
           >>> crumbs = [crumb.items() for crumb in view.getBreadCrumbs()]
           >>> pprint(crumbs)
           [[('url', 'http://127.0.0.1'), ('name', u'[top]')],
-           [('url', 'http://127.0.0.1/zope'), ('name', 'zope')],
+           [('url', 'http://127.0.0.1/zope'), ('name', u'zope')],
            [('url', 'http://127.0.0.1/zope/app'), ('name', 'app')],
            [('url', 'http://127.0.0.1/zope/app/apidoc'), ('name', 'apidoc')],
            [('url', 'http://127.0.0.1/zope/app/apidoc/classmodule'),

Modified: Zope3/trunk/src/zope/app/apidoc/classmodule/configure.zcml
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/configure.zcml	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/configure.zcml	2004-09-11 22:24:02 UTC (rev 27499)
@@ -1,6 +1,7 @@
 <configure
-  xmlns="http://namespaces.zope.org/zope"
-  xmlns:browser="http://namespaces.zope.org/browser">
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:apidoc="http://namespaces.zope.org/apidoc"
+    xmlns:browser="http://namespaces.zope.org/browser">
 
   <class class=".Module">
     <allow interface=".IModuleDocumentation" />
@@ -24,6 +25,12 @@
     <allow attributes="rootModules" />
   </class>
 
+  <apidoc:rootModule module="ZConfig" />
+  <apidoc:rootModule module="ZODB" />
+  <apidoc:rootModule module="transaction" />
+  <apidoc:rootModule module="zdaemon" />
+  <apidoc:rootModule module="zope" />
+
   <utility
     provides="zope.app.apidoc.interfaces.IDocumentationModule"
     factory=".ClassModule"

Added: Zope3/trunk/src/zope/app/apidoc/classmodule/meta.zcml
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/meta.zcml	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/meta.zcml	2004-09-11 22:24:02 UTC (rev 27499)
@@ -0,0 +1,16 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:meta="http://namespaces.zope.org/meta"
+    >
+
+  <meta:directives namespace="http://namespaces.zope.org/apidoc">
+
+    <meta:directive
+        name="rootModule"
+        schema=".metadirectives.IRootModule"
+        handler=".metaconfigure.rootModule"
+        />
+
+  </meta:directives>
+
+</configure>

Added: Zope3/trunk/src/zope/app/apidoc/classmodule/metaconfigure.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/metaconfigure.py	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/metaconfigure.py	2004-09-11 22:24:02 UTC (rev 27499)
@@ -0,0 +1,28 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""This module handles the 'apidoc' namespace directives.
+
+$Id: metaconfigure.py 26889 2004-08-04 04:00:36Z pruggera $
+"""
+__docformat__ = 'restructuredtext'
+from zope.interface import implements
+from zope.app.component.metaconfigure import utility
+from zope.app.apidoc.classmodule import IAPIDocRootModule
+
+class RootModule(str):
+    implements(IAPIDocRootModule)
+
+def rootModule(_context, module):
+    """Register a new module as a root module for the class browser."""
+    utility(_context, IAPIDocRootModule, RootModule(module), name=module)

Added: Zope3/trunk/src/zope/app/apidoc/classmodule/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/metadirectives.py	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/metadirectives.py	2004-09-11 22:24:02 UTC (rev 27499)
@@ -0,0 +1,30 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""``apidoc`` ZCML namespace directive interfaces
+
+$Id: metadirectives.py 26613 2004-07-18 21:50:40Z srichter $
+"""
+__docformat__ = 'restructuredtext'
+from zope.interface import Interface
+from zope.schema import TextLine
+
+class IRootModule(Interface):
+    """Declares a new root module to be available for the class documentation
+    module."""
+
+    module = TextLine(
+        title=u"Root Module Name",
+        description=u"This is the Python path of the new root module.",
+        required=True
+        )

Modified: Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zope/app/apidoc/classmodule/tests.py	2004-09-11 22:24:02 UTC (rev 27499)
@@ -17,7 +17,8 @@
 """
 import unittest
 from zope.component.interfaces import IFactory
-from zope.interface import Interface, directlyProvides
+from zope.configuration import xmlconfig
+from zope.interface import Interface, directlyProvides, implements
 from zope.publisher.browser import TestRequest
 from zope.testing.doctestunit import DocTestSuite
 
@@ -38,7 +39,7 @@
 from zope.app.traversing.adapters import RootPhysicallyLocatable
 from zope.app.traversing.adapters import Traverser
 
-from zope.app.apidoc.classmodule import ClassModule
+from zope.app.apidoc.classmodule import ClassModule, IAPIDocRootModule
 from zope.app.apidoc.classmodule.browser import ClassDetails, ModuleDetails
 from zope.app.apidoc.classmodule.browser import FunctionDetails
 from zope.app.apidoc.interfaces import IDocumentationModule
@@ -46,6 +47,11 @@
 
 def setUp(test):
     placelesssetup.setUp()
+
+    class RootModule(str):
+        implements(IAPIDocRootModule)
+    ztapi.provideUtility(IAPIDocRootModule, RootModule('zope'), "zope")
+
     module = ClassModule()
     module.__name__ = ''
     directlyProvides(module, IContainmentRoot)
@@ -103,11 +109,35 @@
     return view
 
 
+class DirectivesTest(placelesssetup.PlacelessSetup, unittest.TestCase):
+
+    template = """
+        <configure
+            xmlns='http://namespaces.zope.org/apidoc'>
+          %s
+        </configure>"""
+    
+    def setUp(self):
+        super(DirectivesTest, self).setUp()
+        import zope.app.apidoc.classmodule
+        self.context = xmlconfig.file('meta.zcml', zope.app.apidoc.classmodule)
+
+    def testRootModule(self):
+        self.assertEqual(len(list(zapi.getUtilitiesFor(IAPIDocRootModule))), 0)
+        xmlconfig.string(
+            self.template %'<rootModule module="zope" />', self.context)
+
+        self.assertEqual(zapi.getUtilitiesFor(IAPIDocRootModule).next()[0],
+                         'zope')
+
+
 def test_suite():
     return unittest.TestSuite((
         DocTestSuite('zope.app.apidoc.classmodule.browser',
                      setUp=setUp, tearDown=placelesssetup.tearDown),
-        DocTestSuite('zope.app.apidoc.classmodule'),
+        DocTestSuite('zope.app.apidoc.classmodule',
+                     setUp=setUp, tearDown=placelesssetup.tearDown),
+        unittest.makeSuite(DirectivesTest),
         ))
 
 if __name__ == '__main__':

Modified: Zope3/trunk/src/zwiki/configure.zcml
===================================================================
--- Zope3/trunk/src/zwiki/configure.zcml	2004-09-11 17:08:11 UTC (rev 27498)
+++ Zope3/trunk/src/zwiki/configure.zcml	2004-09-11 22:24:02 UTC (rev 27499)
@@ -1,6 +1,7 @@
 <configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:mail="http://namespaces.zope.org/mail"
+   xmlns:apidoc="http://namespaces.zope.org/apidoc"
    i18n_domain="zope"
    >
 
@@ -276,4 +277,7 @@
   <!-- Register various browser related components, including all views -->
   <include package=".browser" />
 
+  <!-- Register application with API Doc Tool -->
+  <apidoc:rootModule module="zwiki" />
+
 </configure>



More information about the Zope3-Checkins mailing list