doc/DocBook.py

   1 #!/usr/bin/python
   2 #
   3 # Generates a DocBook section documenting all PLCAPI methods on
   4 # stdout.
   5 #
   6 # Mark Huang <mlhuang@cs.princeton.edu>
   7 # Copyright (C) 2006 The Trustees of Princeton University
   8 #
   9 # $Id: DocBook.py,v 1.3 2006/10/25 19:35:36 mlhuang Exp $
  10 #
  11
  12 import xml.dom.minidom
  13 from xml.dom.minidom import Element, Text
  14 import codecs
  15
  16 from PLC.Method import *
  17 import DocBookLocal
  18
  19 # xml.dom.minidom.Text.writexml adds surrounding whitespace to textual
  20 # data when pretty-printing. Override this behavior.
  21 class TrimText(Text):
  22     """text"""
  23     def __init__(self, text = None):
  24         self.data = unicode(text)
  25
  26     def writexml(self, writer, indent="", addindent="", newl=""):
  27         Text.writexml(self, writer, "", "", "")
  28
  29 class TrimTextElement(Element):
  30     """<tagName>text</tagName>"""
  31     def __init__(self, tagName, text = None):
  32         Element.__init__(self, tagName)
  33         if text is not None:
  34             self.appendChild(TrimText(text))
  35
  36     def writexml(self, writer, indent="", addindent="", newl=""):
  37         writer.write(indent)
  38         Element.writexml(self, writer, "", "", "")
  39         writer.write(newl)
  40
  41 class simpleElement(TrimTextElement): pass
  42
  43 class paraElement(simpleElement):
  44     """<para>text</para>"""
  45     def __init__(self, text = None):
  46         simpleElement.__init__(self, 'para', text)
  47
  48 class blockquoteElement(Element):
  49     """<blockquote><para>text...</para><para>...text</para></blockquote>"""
  50     def __init__(self, text = None):
  51         Element.__init__(self, 'blockquote')
  52         if text is not None:
  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")
  57
  58             for paragraph in paragraphs:
  59                 self.appendChild(paraElement(paragraph))
  60
  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])
  68     else:
  69         return xmlrpc_type(python_type(param))
  70
  71 class paramElement(Element):
  72     """An optionally named parameter."""
  73     def __init__(self, name, param):
  74         # <listitem>
  75         Element.__init__(self, 'listitem')
  76
  77         description = Element('para')
  78
  79         if name:
  80             description.appendChild(simpleElement('parameter', name))
  81             description.appendChild(TrimText(": "))
  82
  83         description.appendChild(TrimText(param_type(param)))
  84
  85         if isinstance(param, (list, tuple, set)) and len(param) == 1:
  86             param = param[0]
  87
  88         if isinstance(param, Parameter):
  89             description.appendChild(TrimText(", " + param.doc))
  90             param = param.type
  91
  92         self.appendChild(description)
  93
  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))
  99
 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))
 105
 106 api_func_list = DocBookLocal.get_func_list()
 107 for func in api_func_list:
 108     method = func.name
 109
 110     if func.status == "deprecated":
 111         continue
 112
 113     (min_args, max_args, defaults) = func.args()
 114
 115     section = Element('section')
 116     section.setAttribute('id', func.name)
 117     section.appendChild(simpleElement('title', func.name))
 118
 119     prototype = "%s (%s)" % (method, ", ".join(max_args))
 120     para = paraElement('Prototype:')
 121     para.appendChild(blockquoteElement(prototype))
 122     section.appendChild(para)
 123
 124     para = paraElement('Description:')
 125     para.appendChild(blockquoteElement(func.__doc__))
 126     section.appendChild(para)
 127
 128     para = paraElement('Allowed Roles:')
 129     para.appendChild(blockquoteElement(", ".join(func.roles)))
 130     section.appendChild(para)
 131
 132     section.appendChild(paraElement('Parameters:'))
 133     params = Element('itemizedlist')
 134     if func.accepts:
 135         for name, param, default in zip(max_args, func.accepts, defaults):
 136             params.appendChild(paramElement(name, param))
 137     else:
 138         listitem = Element('listitem')
 139         listitem.appendChild(paraElement('None'))
 140         params.appendChild(listitem)
 141     section.appendChild(params)
 142
 143     section.appendChild(paraElement('Returns:'))
 144     returns = Element('itemizedlist')
 145     returns.appendChild(paramElement(None, func.returns))
 146     section.appendChild(returns)
 147
 148     print section.toprettyxml(encoding = "UTF-8")