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
9 # $Id: DocBook.py,v 1.3 2006/10/25 19:35:36 mlhuang Exp $
12 import xml.dom.minidom
13 from xml.dom.minidom import Element, Text
16 from PLC.Method import *
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))
106 api_func_list = DocBookLocal.get_func_list()
107 for func in api_func_list:
110 if func.status == "deprecated":
113 (min_args, max_args, defaults) = func.args()
115 section = Element('section')
116 section.setAttribute('id', func.name)
117 section.appendChild(simpleElement('title', func.name))
119 prototype = "%s (%s)" % (method, ", ".join(max_args))
120 para = paraElement('Prototype:')
121 para.appendChild(blockquoteElement(prototype))
122 section.appendChild(para)
124 para = paraElement('Description:')
125 para.appendChild(blockquoteElement(func.__doc__))
126 section.appendChild(para)
128 para = paraElement('Allowed Roles:')
129 para.appendChild(blockquoteElement(", ".join(func.roles)))
130 section.appendChild(para)
132 section.appendChild(paraElement('Parameters:'))
133 params = Element('itemizedlist')
135 for name, param, default in zip(max_args, func.accepts, defaults):
136 params.appendChild(paramElement(name, param))
138 listitem = Element('listitem')
139 listitem.appendChild(paraElement('None'))
140 params.appendChild(listitem)
141 section.appendChild(params)
143 section.appendChild(paraElement('Returns:'))
144 returns = Element('itemizedlist')
145 returns.appendChild(paramElement(None, func.returns))
146 section.appendChild(returns)
148 print section.toprettyxml(encoding = "UTF-8")