[Zope3-checkins] CVS: Zope3/utilities - makezcmldocs.py:1.2 makezcmldocs.zcml:1.2
R. David Murray
bitz@bitdance.com
Wed, 6 Nov 2002 17:30:23 -0500
Update of /cvs-repository/Zope3/utilities
In directory cvs.zope.org:/tmp/cvs-serv10913/utilities
Added Files:
makezcmldocs.py makezcmldocs.zcml
Log Message:
Merge of rdmurray-metameta-branch. See checkin message for
doc/zcml/meta.stx for a more comprehensive checkin comment.
=== Zope3/utilities/makezcmldocs.py 1.1 => 1.2 ===
--- /dev/null Wed Nov 6 17:30:23 2002
+++ Zope3/utilities/makezcmldocs.py Wed Nov 6 17:30:23 2002
@@ -0,0 +1,147 @@
+#! /usr/bin/env python2.2
+##############################################################################
+#
+# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (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.
+#
+##############################################################################
+"""
+
+$Id$
+"""
+
+from types import UnicodeType, FunctionType, TypeType, ClassType
+import os, sys
+try: from textwrap import TextWrapper
+except:
+ class TextWrapper:
+ def __init__(self,initial_indent='',**kw):
+ self.initial_indent = initial_indent
+ def fill(self,txt):
+ t = txt.split()
+ i = 0; res = []
+ while i*10 <= len(t):
+ res.append(self.initial_indent+' '.join(t[i*10:(i+1)*10]))
+ i += 1
+ return '\n'.join(res)
+
+# Get Zope3 stuff in the pythonpath. Note that we use 'here' later as well.
+basepath = filter(None, sys.path)
+here = os.path.normpath(os.path.join(os.getcwd(),
+ os.path.split(sys.argv[0])[0]))
+root = os.path.split(here)[0] #We live in the utilities subdirectory
+libpython = os.path.join(root, 'lib', 'python')
+sys.path=[libpython] + basepath
+
+# Now for the z3 imports.
+from Zope.Configuration.meta import _directives
+from Zope.Configuration.metametaConfigureForDocgen import _metadataKey
+
+# Some additional useful names.
+treeroot = os.path.join(root,'doc','zcml.new') #Where we put the docs.
+wrapper = TextWrapper(width=75, replace_whitespace=False)
+paragraph = wrapper.fill
+
+def handlerData(handler,metadata):
+ """Normalize information about the handler for a directive
+
+ Returns a tuple of a path and a description. The path is an
+ attempt to get something resembling the directory containing
+ the zcml defining the directive, by guessing that the meta.zcml
+ file is in the same directory as the handler. THIS NEEDS FIXING.
+ If the handler is a method, we return blank, since we have no
+ information to base a guess on. The description is a string
+ consiting of the type of the handler (function, method, class,
+ type) and either the name (for a method) or the full python
+ path to the handler.
+ """
+ if type(handler)==FunctionType:
+ parts = metadata['handler'].split('.')
+ path = '.'.join(parts[:-2])
+ name = parts[-1]
+ typ = 'function'
+ elif type(handler)==TypeType:
+ path = '.'.join(handler.__module__.split('.')[:-1])
+ name = handler.__name__
+ typ = 'type'
+ elif type(handler)==ClassType:
+ path = '.'.join(handler.__module__.split('.')[:-1])
+ name = handler.__name__
+ typ = 'class'
+ elif type(handler)==UnicodeType:
+ path = ''
+ name = handler
+ typ = 'method'
+ return path, "%s %s%s" % (typ,path and path+'.' or '',name)
+
+# This should really be refactored so you can see what's actually
+# going on here.
+def printdirective(outfile, name, handler, registry, level=0):
+ global curpath
+ if level>10: return
+ wrapper.initial_indent = wrapper.subsequent_indent = ' '*level
+ fileshortname = outfile.name[len(treeroot)+1:-4]
+ ns, name = name
+ md = registry[_metadataKey]
+ path, handlerstring = handlerData(handler,md)
+ if path: curpath = path
+ outfile.write("%s%s (%s)\n\n" % (' '*level, name, handlerstring))
+ wrapper.initial_indent = wrapper.subsequent_indent = ' '*(level+2)
+ description = md.get('description','')
+ if description: outfile.write(paragraph(description)+'\n\n')
+ else: sys.stderr.write("%s in %s has no description\n" % (name, curpath))
+ wrapper.subsequent_indent = ' '*(level+4)
+ for attr in md['attributes']:
+ amd = md['attributes'][attr]
+ description = amd.get('description','')
+ if not description: sys.stderr.write(("%s in %s has no description " +
+ "for the %s attribute") % (fileshortname, curpath, attr))
+ required = amd.get('required')
+ required = (required=='yes' and '(required) ' or required=='no' and
+ '(optional) ' or '')
+ outfile.write(paragraph("%s -- %s%s" % (attr,required,
+ description))+'\n\n')
+ if (level<9 and len(registry)>1 or len(registry)==1 and not
+ registry.keys()==[_metadataKey]):
+ outfile.write(' '*level+'Subdirectives\n\n')
+ for subdir in registry:
+ if subdir==_metadataKey: continue
+ subs, handler = registry[subdir]
+ printdirective(outfile, subdir, handler, subs, level+2)
+
+
+def run(argv=sys.argv):
+
+ from Zope.Configuration.xmlconfig import XMLConfig
+
+ # Set user to system_user, so we can do anything we want
+ from Zope.Security.SecurityManagement import system_user
+ from Zope.Security.SecurityManagement import newSecurityManager
+ newSecurityManager(system_user)
+
+ # Load the zcml for the Zope package in docgen mode.
+ XMLConfig(os.path.join(here, 'makezcmldocs.zcml'))()
+
+ # Build the meta docs from the contents of the directive registry.
+ if not os.path.exists(treeroot): os.mkdir(treeroot)
+ for directive in _directives:
+ ns, name = directive
+ ns = ns[7:]
+ nspath = os.path.join(treeroot,ns)
+ if not os.path.exists(nspath): os.makedirs(nspath)
+ filepath = os.path.join(nspath,'%s.stx' % name)
+ dirfile = open(filepath,'w')
+ callable, subs = _directives[directive]
+ printdirective(dirfile, directive, callable, subs)
+
+
+if __name__ == '__main__':
+ run()
+
=== Zope3/utilities/makezcmldocs.zcml 1.1 => 1.2 ===
--- /dev/null Wed Nov 6 17:30:23 2002
+++ Zope3/utilities/makezcmldocs.zcml Wed Nov 6 17:30:23 2002
@@ -0,0 +1,7 @@
+<zopeConfigure xmlns='http://namespaces.zope.org/zope'>
+
+<include package="Zope/Configuration" file="metameta.zcml" />
+<include package="Zope/Configuration" file="metametaForDocgen.zcml" />
+<include package="Zope" />
+
+</zopeConfigure>