X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=doc%2FDocBook.py;h=90b384d7f189025b98f816f278b53dfe1b4e5cef;hb=HEAD;hp=a62ef9b6c8b20ffb5b2762b928e9d89ac0d36bbf;hpb=24d16d18acab3da7bccc3e09df4927e9cf2d3246;p=plcapi.git diff --git a/doc/DocBook.py b/doc/DocBook.py index a62ef9b..90b384d 100755 --- a/doc/DocBook.py +++ b/doc/DocBook.py @@ -6,38 +6,36 @@ # Mark Huang # Copyright (C) 2006 The Trustees of Princeton University # -# $Id$ -# import xml.dom.minidom from xml.dom.minidom import Element, Text import codecs -from PLC.API import PLCAPI -from PLC.Method import * - -api = PLCAPI(None) +from PLC.Parameter import Parameter, Mixed, xmlrpc_type, python_type # 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,166 +55,97 @@ 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, default, 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 - row.appendChild(entryElement(str(bool(optional)))) - - # Parameter default - if optional and default is not None: - row.appendChild(entryElement(unicode(default))) +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()) - - # Parameter documentation - row.appendChild(entryElement(doc)) - - # 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] - - for name, subparam in subparams: - if isinstance(subparam, Parameter): - (optional, default, doc) = (subparam.optional, subparam.default, subparam.doc) - else: - # All named sub-parameters are optional if not otherwise specified - (optional, default, doc) = (True, None, "") - rows += parameters(subparam, name, optional, default, doc, indent + step, step) - - return rows - -for method in api.methods: - func = api.callable(method) - (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)) - section.appendChild(para) - - para = paraElement('Description:') - para.appendChild(blockquoteElement(func.__doc__)) - section.appendChild(para) - - para = paraElement('Parameters:') - blockquote = blockquoteElement() - para.appendChild(blockquote) - section.appendChild(para) - - head = rowElement(['Name', 'Type', 'Optional', 'Default', 'Description']) - rows = [] - - indent = " " - for name, param, default in zip(max_args, func.accepts, defaults): - optional = name not in min_args + 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(": ")) + + description.appendChild(TrimText(param_type(param))) + + if isinstance(param, (list, tuple, set)) and len(param) == 1: + param = param[0] + if isinstance(param, Parameter): - doc = param.doc - else: - doc = "" - rows += parameters(param, name, optional, default, doc, "", indent) - - if rows: - informaltable = informaltableElement(head, rows) - informaltable.setAttribute('frame', "none") - informaltable.setAttribute('rules', "rows") - blockquote.appendChild(informaltable) - else: - blockquote.appendChild(paraElement("None")) + description.appendChild(TrimText(", " + param.doc)) + param = param.type + + self.appendChild(description) + + 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)) + +class DocBook: + + def __init__ (self,functions_list): + self.functions_list = functions_list + + def Process (self): + + for func in self.functions_list: + method = func.name + + 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)) + + prototype = "%s (%s)" % (method, ", ".join(max_args)) + para = paraElement('Prototype:') + para.appendChild(blockquoteElement(prototype)) + section.appendChild(para) + + para = paraElement('Description:') + para.appendChild(blockquoteElement(func.__doc__)) + section.appendChild(para) + + para = paraElement('Allowed Roles:') + para.appendChild(blockquoteElement(", ".join(func.roles))) + section.appendChild(para) + + 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: + 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") + print section.toprettyxml(encoding = "UTF-8")