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.4 2007/02/19 18:02:39 mlhuang Exp $
12 import xml.dom.minidom
13 from xml.dom.minidom import Element, Text
16 from PLC.API import PLCAPI
17 from PLC.Method import *
21 # xml.dom.minidom.Text.writexml adds surrounding whitespace to textual
22 # data when pretty-printing. Override this behavior.
25 def __init__(self, text = None):
26 self.data = unicode(text)
28 def writexml(self, writer, indent="", addindent="", newl=""):
29 Text.writexml(self, writer, "", "", "")
31 class TrimTextElement(Element):
32 """<tagName>text</tagName>"""
33 def __init__(self, tagName, text = None):
34 Element.__init__(self, tagName)
36 self.appendChild(TrimText(text))
38 def writexml(self, writer, indent="", addindent="", newl=""):
40 Element.writexml(self, writer, "", "", "")
43 class simpleElement(TrimTextElement): pass
45 class paraElement(simpleElement):
46 """<para>text</para>"""
47 def __init__(self, text = None):
48 simpleElement.__init__(self, 'para', text)
50 class blockquoteElement(Element):
51 """<blockquote><para>text...</para><para>...text</para></blockquote>"""
52 def __init__(self, text = None):
53 Element.__init__(self, 'blockquote')
55 # Split on blank lines
56 lines = [line.strip() for line in text.strip().split("\n")]
57 lines = "\n".join(lines)
58 paragraphs = lines.split("\n\n")
60 for paragraph in paragraphs:
61 self.appendChild(paraElement(paragraph))
63 def param_type(param):
64 """Return the XML-RPC type of a parameter."""
65 if isinstance(param, Mixed) and len(param):
66 subtypes = [param_type(subparam) for subparam in param]
67 return " or ".join(subtypes)
68 elif isinstance(param, (list, tuple, set)) and len(param):
69 return "array of " + " or ".join([param_type(subparam) for subparam in param])
71 return xmlrpc_type(python_type(param))
73 class paramElement(Element):
74 """An optionally named parameter."""
75 def __init__(self, name, param):
77 Element.__init__(self, 'listitem')
79 description = Element('para')
82 description.appendChild(simpleElement('parameter', name))
83 description.appendChild(TrimText(": "))
85 description.appendChild(TrimText(param_type(param)))
87 if isinstance(param, (list, tuple, set)) and len(param) == 1:
90 if isinstance(param, Parameter):
91 description.appendChild(TrimText(", " + param.doc))
94 self.appendChild(description)
96 if isinstance(param, dict):
97 itemizedlist = Element('itemizedlist')
98 self.appendChild(itemizedlist)
99 for name, subparam in param.iteritems():
100 itemizedlist.appendChild(paramElement(name, subparam))
102 elif isinstance(param, (list, tuple, set)) and len(param):
103 itemizedlist = Element('itemizedlist')
104 self.appendChild(itemizedlist)
105 for subparam in param:
106 itemizedlist.appendChild(paramElement(None, subparam))
108 for method in api.methods:
109 func = api.callable(method)
111 if func.status == "deprecated":
114 (min_args, max_args, defaults) = func.args()
116 section = Element('section')
117 section.setAttribute('id', func.name)
118 section.appendChild(simpleElement('title', func.name))
120 prototype = "%s (%s)" % (method, ", ".join(max_args))
121 para = paraElement('Prototype:')
122 para.appendChild(blockquoteElement(prototype))
123 section.appendChild(para)
125 para = paraElement('Description:')
126 para.appendChild(blockquoteElement(func.__doc__))
127 section.appendChild(para)
129 para = paraElement('Allowed Roles:')
130 para.appendChild(blockquoteElement(", ".join(func.roles)))
131 section.appendChild(para)
133 section.appendChild(paraElement('Parameters:'))
134 params = Element('itemizedlist')
136 for name, param, default in zip(max_args, func.accepts, defaults):
137 params.appendChild(paramElement(name, param))
139 listitem = Element('listitem')
140 listitem.appendChild(paraElement('None'))
141 params.appendChild(listitem)
142 section.appendChild(params)
144 section.appendChild(paraElement('Returns:'))
145 returns = Element('itemizedlist')
146 returns.appendChild(paramElement(None, func.returns))
147 section.appendChild(returns)
149 print section.toprettyxml(encoding = "UTF-8")