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
10 import xml.dom.minidom
11 from xml.dom.minidom import Element, Text
14 from PLC.Parameter import Parameter, Mixed, xmlrpc_type, python_type
16 # xml.dom.minidom.Text.writexml adds surrounding whitespace to textual
17 # data when pretty-printing. Override this behavior.
20 def __init__(self, text = None):
21 self.data = unicode(text)
23 def writexml(self, writer, indent="", addindent="", newl=""):
24 Text.writexml(self, writer, "", "", "")
26 class TrimTextElement(Element):
27 """<tagName>text</tagName>"""
28 def __init__(self, tagName, text = None):
29 Element.__init__(self, tagName)
31 self.appendChild(TrimText(text))
33 def writexml(self, writer, indent="", addindent="", newl=""):
35 Element.writexml(self, writer, "", "", "")
38 class simpleElement(TrimTextElement): pass
40 class paraElement(simpleElement):
41 """<para>text</para>"""
42 def __init__(self, text = None):
43 simpleElement.__init__(self, 'para', text)
45 class blockquoteElement(Element):
46 """<blockquote><para>text...</para><para>...text</para></blockquote>"""
47 def __init__(self, text = None):
48 Element.__init__(self, 'blockquote')
50 # Split on blank lines
51 lines = [line.strip() for line in text.strip().split("\n")]
52 lines = "\n".join(lines)
53 paragraphs = lines.split("\n\n")
55 for paragraph in paragraphs:
56 self.appendChild(paraElement(paragraph))
58 def param_type(param):
59 """Return the XML-RPC type of a parameter."""
60 if isinstance(param, Mixed) and len(param):
61 subtypes = [param_type(subparam) for subparam in param]
62 return " or ".join(subtypes)
63 elif isinstance(param, (list, tuple, set)) and len(param):
64 return "array of " + " or ".join([param_type(subparam) for subparam in param])
66 return xmlrpc_type(python_type(param))
68 class paramElement(Element):
69 """An optionally named parameter."""
70 def __init__(self, name, param):
72 Element.__init__(self, 'listitem')
74 description = Element('para')
77 description.appendChild(simpleElement('parameter', name))
78 description.appendChild(TrimText(": "))
80 description.appendChild(TrimText(param_type(param)))
82 if isinstance(param, (list, tuple, set)) and len(param) == 1:
85 if isinstance(param, Parameter):
86 description.appendChild(TrimText(", " + param.doc))
89 self.appendChild(description)
91 if isinstance(param, dict):
92 itemizedlist = Element('itemizedlist')
93 self.appendChild(itemizedlist)
94 for name, subparam in param.iteritems():
95 itemizedlist.appendChild(paramElement(name, subparam))
97 elif isinstance(param, (list, tuple, set)) and len(param):
98 itemizedlist = Element('itemizedlist')
99 self.appendChild(itemizedlist)
100 for subparam in param:
101 itemizedlist.appendChild(paramElement(None, subparam))
105 def __init__ (self,functions_list):
106 self.functions_list = functions_list
110 for func in self.functions_list:
113 if func.status == "deprecated":
116 (min_args, max_args, defaults) = func.args()
118 section = Element('section')
119 section.setAttribute('id', func.name)
120 section.appendChild(simpleElement('title', func.name))
122 prototype = "%s (%s)" % (method, ", ".join(max_args))
123 para = paraElement('Prototype:')
124 para.appendChild(blockquoteElement(prototype))
125 section.appendChild(para)
127 para = paraElement('Description:')
128 para.appendChild(blockquoteElement(func.__doc__))
129 section.appendChild(para)
131 para = paraElement('Allowed Roles:')
132 para.appendChild(blockquoteElement(", ".join(func.roles)))
133 section.appendChild(para)
135 section.appendChild(paraElement('Parameters:'))
136 params = Element('itemizedlist')
138 for name, param, default in zip(max_args, func.accepts, defaults):
139 params.appendChild(paramElement(name, param))
141 listitem = Element('listitem')
142 listitem.appendChild(paraElement('None'))
143 params.appendChild(listitem)
144 section.appendChild(params)
146 section.appendChild(paraElement('Returns:'))
147 returns = Element('itemizedlist')
148 returns.appendChild(paramElement(None, func.returns))
149 section.appendChild(returns)
151 print section.toprettyxml(encoding = "UTF-8")