3 # Generates a DocBook section documenting all PLCAPI methods on
6 # Mark Huang <mlhuang@cs.princeton.edu>
7 # Copyright (C) 2006 The Trustees of Princeton University
13 import xml.dom.minidom
14 from xml.dom.minidom import Element, Text
17 from PLC.Parameter import Parameter, Mixed, xmlrpc_type, python_type
19 # xml.dom.minidom.Text.writexml adds surrounding whitespace to textual
20 # data when pretty-printing. Override this behavior.
23 def __init__(self, text = None):
24 self.data = unicode(text)
26 def writexml(self, writer, indent="", addindent="", newl=""):
27 Text.writexml(self, writer, "", "", "")
29 class TrimTextElement(Element):
30 """<tagName>text</tagName>"""
31 def __init__(self, tagName, text = None):
32 Element.__init__(self, tagName)
34 self.appendChild(TrimText(text))
36 def writexml(self, writer, indent="", addindent="", newl=""):
38 Element.writexml(self, writer, "", "", "")
41 class simpleElement(TrimTextElement): pass
43 class paraElement(simpleElement):
44 """<para>text</para>"""
45 def __init__(self, text = None):
46 simpleElement.__init__(self, 'para', text)
48 class blockquoteElement(Element):
49 """<blockquote><para>text...</para><para>...text</para></blockquote>"""
50 def __init__(self, text = None):
51 Element.__init__(self, 'blockquote')
53 # Split on blank lines
54 lines = [line.strip() for line in text.strip().split("\n")]
55 lines = "\n".join(lines)
56 paragraphs = lines.split("\n\n")
58 for paragraph in paragraphs:
59 self.appendChild(paraElement(paragraph))
61 def param_type(param):
62 """Return the XML-RPC type of a parameter."""
63 if isinstance(param, Mixed) and len(param):
64 subtypes = [param_type(subparam) for subparam in param]
65 return " or ".join(subtypes)
66 elif isinstance(param, (list, tuple, set)) and len(param):
67 return "array of " + " or ".join([param_type(subparam) for subparam in param])
69 return xmlrpc_type(python_type(param))
71 class paramElement(Element):
72 """An optionally named parameter."""
73 def __init__(self, name, param):
75 Element.__init__(self, 'listitem')
77 description = Element('para')
80 description.appendChild(simpleElement('parameter', name))
81 description.appendChild(TrimText(": "))
83 description.appendChild(TrimText(param_type(param)))
85 if isinstance(param, (list, tuple, set)) and len(param) == 1:
88 if isinstance(param, Parameter):
89 description.appendChild(TrimText(", " + param.doc))
92 self.appendChild(description)
94 if isinstance(param, dict):
95 itemizedlist = Element('itemizedlist')
96 self.appendChild(itemizedlist)
97 for name, subparam in param.iteritems():
98 itemizedlist.appendChild(paramElement(name, subparam))
100 elif isinstance(param, (list, tuple, set)) and len(param):
101 itemizedlist = Element('itemizedlist')
102 self.appendChild(itemizedlist)
103 for subparam in param:
104 itemizedlist.appendChild(paramElement(None, subparam))
108 def __init__ (self,functions_list):
109 self.functions_list = functions_list
113 for func in self.functions_list:
116 if func.status == "deprecated":
119 (min_args, max_args, defaults) = func.args()
121 section = Element('section')
122 section.setAttribute('id', func.name)
123 section.appendChild(simpleElement('title', func.name))
125 prototype = "%s (%s)" % (method, ", ".join(max_args))
126 para = paraElement('Prototype:')
127 para.appendChild(blockquoteElement(prototype))
128 section.appendChild(para)
130 para = paraElement('Description:')
131 para.appendChild(blockquoteElement(func.__doc__))
132 section.appendChild(para)
134 para = paraElement('Allowed Roles:')
135 para.appendChild(blockquoteElement(", ".join(func.roles)))
136 section.appendChild(para)
138 section.appendChild(paraElement('Parameters:'))
139 params = Element('itemizedlist')
141 for name, param, default in zip(max_args, func.accepts, defaults):
142 params.appendChild(paramElement(name, param))
144 listitem = Element('listitem')
145 listitem.appendChild(paraElement('None'))
146 params.appendChild(listitem)
147 section.appendChild(params)
149 section.appendChild(paraElement('Returns:'))
150 returns = Element('itemizedlist')
151 returns.appendChild(paramElement(None, func.returns))
152 section.appendChild(returns)
154 print section.toprettyxml(encoding = "UTF-8")