From 16c88e6e4e609facf12f7d36d63551089138d35b Mon Sep 17 00:00:00 2001 From: Mark Huang Date: Mon, 19 Feb 2007 18:02:39 +0000 Subject: [PATCH] - simplify doc output; use itemizedlists instead of tables to further describe structs/array/mixed types. If an array is composed of just one subtype, abbreviate the list generation by one level. --- doc/DocBook.py | 228 +++++++++++++++---------------------------------- 1 file changed, 71 insertions(+), 157 deletions(-) diff --git a/doc/DocBook.py b/doc/DocBook.py index 84a5121..0185ab4 100755 --- a/doc/DocBook.py +++ b/doc/DocBook.py @@ -6,7 +6,7 @@ # Mark Huang # Copyright (C) 2006 The Trustees of Princeton University # -# $Id: DocBook.py,v 1.2 2006/10/25 14:32:01 mlhuang Exp $ +# $Id: DocBook.py,v 1.3 2006/10/25 19:35:36 mlhuang Exp $ # import xml.dom.minidom @@ -21,23 +21,26 @@ api = PLCAPI(None) # xml.dom.minidom.Text.writexml adds surrounding whitespace to textual # data when pretty-printing. Override this behavior. class TrimText(Text): + """text""" + def __init__(self, text = None): + self.data = unicode(text) + def writexml(self, writer, indent="", addindent="", newl=""): Text.writexml(self, writer, "", "", "") class TrimTextElement(Element): + """text""" + def __init__(self, tagName, text = None): + Element.__init__(self, tagName) + if text is not None: + self.appendChild(TrimText(text)) + def writexml(self, writer, indent="", addindent="", newl=""): writer.write(indent) Element.writexml(self, writer, "", "", "") writer.write(newl) -class simpleElement(TrimTextElement): - """text""" - def __init__(self, tagName, text = None): - TrimTextElement.__init__(self, tagName) - if text is not None: - t = TrimText() - t.data = unicode(text) - self.appendChild(t) +class simpleElement(TrimTextElement): pass class paraElement(simpleElement): """text""" @@ -57,130 +60,63 @@ class blockquoteElement(Element): for paragraph in paragraphs: self.appendChild(paraElement(paragraph)) -class entryElement(simpleElement): - """text""" - def __init__(self, text = None): - simpleElement.__init__(self, 'entry', text) - -class rowElement(Element): - """ - - entries[0] - entries[1] - ... - - """ - - def __init__(self, entries = None): - Element.__init__(self, 'row') - if entries: - for entry in entries: - if isinstance(entry, entryElement): - self.appendChild(entry) - else: - self.appendChild(entryElement(entry)) - -class informaltableElement(Element): - """ - - - - - label1 - label2 - ... - - - - - row1value1 - row1value2 - ... - - ... - - - - """ - - def __init__(self, head = None, rows = None): - Element.__init__(self, 'informaltable') - tgroup = Element('tgroup') - self.appendChild(tgroup) - if head: - thead = Element('thead') - tgroup.appendChild(thead) - if isinstance(head, rowElement): - thead.appendChild(head) - else: - thead.appendChild(rowElement(head)) - if rows: - tbody = Element('tbody') - tgroup.appendChild(tbody) - for row in rows: - if isinstance(row, rowElement): - tbody.appendChild(row) - else: - tobdy.appendChild(rowElement(row)) - cols = len(thead.childNodes[0].childNodes) - tgroup.setAttribute('cols', str(cols)) - -def parameters(param, name, optional, doc, indent, step): - """Format a parameter into parameter row(s).""" - - rows = [] - - row = rowElement() - rows.append(row) - - # Parameter name - entry = entryElement() - entry.appendChild(simpleElement('literallayout', indent + name)) - row.appendChild(entry) - - # Parameter type - param_type = python_type(param) - row.appendChild(entryElement(xmlrpc_type(param_type))) - - # Whether parameter is optional - if optional is not None: - row.appendChild(entryElement(str(bool(optional)))) +def param_type(param): + """Return the XML-RPC type of a parameter.""" + if isinstance(param, Mixed) and len(param): + subtypes = [param_type(subparam) for subparam in param] + return " or ".join(subtypes) + elif isinstance(param, (list, tuple, set)) and len(param): + return "array of " + " or ".join([param_type(subparam) for subparam in param]) else: - row.appendChild(entryElement("")) + return xmlrpc_type(python_type(param)) + +class paramElement(Element): + """An optionally named parameter.""" + def __init__(self, name, param): + # + Element.__init__(self, 'listitem') + + description = Element('para') + + if name: + description.appendChild(simpleElement('parameter', name)) + description.appendChild(TrimText(": ")) - # Parameter documentation - row.appendChild(entryElement(doc)) + description.appendChild(TrimText(param_type(param))) - # Indent the name of each sub-parameter - subparams = [] - if isinstance(param, dict): - subparams = param.iteritems() - elif isinstance(param, Mixed): - subparams = [(name, subparam) for subparam in param] - elif isinstance(param, (list, tuple)): - subparams = [("", subparam) for subparam in param] + if isinstance(param, (list, tuple, set)) and len(param) == 1: + param = param[0] - for name, subparam in subparams: - if isinstance(subparam, Parameter): - (optional, doc) = (subparam.optional, subparam.doc) - else: - (optional, doc) = (None, "") - rows += parameters(subparam, name, optional, doc, indent + step, step) + if isinstance(param, Parameter): + description.appendChild(TrimText(", " + param.doc)) + param = param.type + + self.appendChild(description) - return rows + if isinstance(param, dict): + itemizedlist = Element('itemizedlist') + self.appendChild(itemizedlist) + for name, subparam in param.iteritems(): + itemizedlist.appendChild(paramElement(name, subparam)) + + elif isinstance(param, (list, tuple, set)) and len(param): + itemizedlist = Element('itemizedlist') + self.appendChild(itemizedlist) + for subparam in param: + itemizedlist.appendChild(paramElement(None, subparam)) for method in api.methods: func = api.callable(method) + + if func.status == "deprecated": + continue + (min_args, max_args, defaults) = func.args() section = Element('section') section.setAttribute('id', func.name) section.appendChild(simpleElement('title', func.name)) - para = paraElement('Status:') - para.appendChild(blockquoteElement(func.status)) - section.appendChild(para) - prototype = "%s (%s)" % (method, ", ".join(max_args)) para = paraElement('Prototype:') para.appendChild(blockquoteElement(prototype)) @@ -190,46 +126,24 @@ for method in api.methods: para.appendChild(blockquoteElement(func.__doc__)) section.appendChild(para) - para = paraElement('Parameters:') - blockquote = blockquoteElement() - para.appendChild(blockquote) - section.appendChild(para) - - head = rowElement(['Name', 'Type', 'Optional', 'Description']) - rows = [] - - indent = " " - for name, param, default in zip(max_args, func.accepts, defaults): - optional = name not in min_args - if isinstance(param, Parameter): - doc = param.doc - else: - doc = "" - rows += parameters(param, name, optional, doc, "", indent) - - if rows: - informaltable = informaltableElement(head, rows) - informaltable.setAttribute('frame', "none") - informaltable.setAttribute('rules', "rows") - blockquote.appendChild(informaltable) - else: - blockquote.appendChild(paraElement("None")) - - para = paraElement('Returns:') - blockquote = blockquoteElement() - para.appendChild(blockquote) + para = paraElement('Allowed Roles:') + para.appendChild(blockquoteElement(", ".join(func.roles))) section.appendChild(para) - head = rowElement(['Name', 'Type', 'Optional', 'Description']) - if isinstance(func.returns, Parameter): - doc = func.returns.doc + section.appendChild(paraElement('Parameters:')) + params = Element('itemizedlist') + if func.accepts: + for name, param, default in zip(max_args, func.accepts, defaults): + params.appendChild(paramElement(name, param)) else: - doc = "" - indent = " " - rows = parameters(func.returns, "", None, doc, "", indent) - informaltable = informaltableElement(head, rows) - informaltable.setAttribute('frame', "none") - informaltable.setAttribute('rules', "rows") - blockquote.appendChild(informaltable) + listitem = Element('listitem') + listitem.appendChild(paraElement('None')) + params.appendChild(listitem) + section.appendChild(params) + + section.appendChild(paraElement('Returns:')) + returns = Element('itemizedlist') + returns.appendChild(paramElement(None, func.returns)) + section.appendChild(returns) print section.toprettyxml(encoding = "UTF-8") -- 2.43.0