#!/usr/bin/env python2 """Doxygen XML to SWIG docstring converter. Usage: doxy2swig.py [options] input.xml output.i Converts Doxygen generated XML files into a file containing docstrings that can be used by SWIG-1.3.x. Note that you need to get SWIG version > 1.3.23 or use Robin Dunn's docstring patch to be able to use the resulting output. input.xml is your doxygen generated XML file and output.i is where the output will be written (the file will be clobbered). """ # # # This code is implemented using Mark Pilgrim's code as a guideline: # http://www.faqs.org/docs/diveintopython/kgp_divein.html # # Author: Prabhu Ramachandran # License: BSD style # # Thanks: # Johan Hake: the include_function_definition feature # Bill Spotz: bug reports and testing. # Sebastian Henschel: Misc. enhancements. # # from xml.dom import minidom import re import textwrap import sys import os.path import optparse def my_open_read(source): if hasattr(source, "read"): return source else: return open(source) def my_open_write(dest): if hasattr(dest, "write"): return dest else: return open(dest, 'w') class Doxy2SWIG: """Converts Doxygen generated XML files into a file containing docstrings that can be used by SWIG-1.3.x that have support for feature("docstring"). Once the data is parsed it is stored in self.pieces. """ def __init__(self, src, include_function_definition=True, quiet=False): """Initialize the instance given a source object. `src` can be a file or filename. If you do not want to include function definitions from doxygen then set `include_function_definition` to `False`. This is handy since this allows you to use the swig generated function definition using %feature("autodoc", [0,1]). """ f = my_open_read(src) self.my_dir = os.path.dirname(f.name) self.xmldoc = minidom.parse(f).documentElement f.close() self.pieces = [] self.pieces.append('\n// File: %s\n' % os.path.basename(f.name)) self.space_re = re.compile(r'\s+') self.lead_spc = re.compile(r'^(%feature\S+\s+\S+\s*?)"\s+(\S)') self.multi = 0 self.ignores = ['inheritancegraph', 'param', 'listofallmembers', 'innerclass', 'name', 'declname', 'incdepgraph', 'invincdepgraph', 'programlisting', 'type', 'references', 'referencedby', 'location', 'collaborationgraph', 'reimplements', 'reimplementedby', 'derivedcompoundref', 'basecompoundref'] #self.generics = [] self.include_function_definition = include_function_definition if not include_function_definition: self.ignores.append('argsstring') self.quiet = quiet def generate(self): """Parses the file set in the initialization. The resulting data is stored in `self.pieces`. """ self.parse(self.xmldoc) def parse(self, node): """Parse a given node. This function in turn calls the `parse_<nodeType>` functions which handle the respective nodes. """ pm = getattr(self, "parse_%s" % node.__class__.__name__) pm(node) def parse_Document(self, node): self.parse(node.documentElement) def parse_Text(self, node): txt = node.data txt = txt.replace('\\', r'\\\\') txt = txt.replace('"', r'\"') # ignore pure whitespace m = self.space_re.match(txt) if m and len(m.group()) == len(txt): pass else: self.add_text(textwrap.fill(txt, break_long_words=False)) def parse_Element(self, node): """Parse an `ELEMENT_NODE`. This calls specific `do_<tagName>` handers for different elements. If no handler is available the `generic_parse` method is called. All tagNames specified in `self.ignores` are simply ignored. """ name = node.tagName ignores = self.ignores if name in ignores: return attr = "do_%s" % name if hasattr(self, attr): handlerMethod = getattr(self, attr) handlerMethod(node) else: self.generic_parse(node) #if name not in self.generics: self.generics.append(name) def parse_Comment(self, node): """Parse a `COMMENT_NODE`. This does nothing for now.""" return def add_text(self, value): """Adds text corresponding to `value` into `self.pieces`.""" if isinstance(value, (list, tuple)): self.pieces.extend(value) else: self.pieces.append(value) def get_specific_nodes(self, node, names): """Given a node and a sequence of strings in `names`, return a dictionary containing the names as keys and child `ELEMENT_NODEs`, that have a `tagName` equal to the name. """ nodes = [(x.tagName, x) for x in node.childNodes if x.nodeType == x.ELEMENT_NODE and x.tagName in names] return dict(nodes) def generic_parse(self, node, pad=0): """A Generic parser for arbitrary tags in a node. Parameters: - node: A node in the DOM. - pad: `int` (default: 0) If 0 the node data is not padded with newlines. If 1 it appends a newline after parsing the childNodes. If 2 it pads before and after the nodes are processed. Defaults to 0. """ npiece = 0 if pad: npiece = len(self.pieces) if pad == 2: self.add_text('\n') for n in node.childNodes: self.parse(n) if pad: if len(self.pieces) > npiece: self.add_text('\n') def space_parse(self, node): self.add_text(' ') self.generic_parse(node) do_ref = space_parse do_emphasis = space_parse do_bold = space_parse do_computeroutput = space_parse do_formula = space_parse def do_compoundname(self, node): self.add_text('\n\n') data = node.firstChild.data self.add_text('%%feature("docstring") %s "\n' % data) def do_compounddef(self, node): kind = node.attributes['kind'].value if kind in ('class', 'struct'): prot = node.attributes['prot'].value if prot != 'public': return names = ('compoundname', 'briefdescription', 'detaileddescription', 'includes') first = self.get_specific_nodes(node, names) for n in names: if first.has_key(n): self.parse(first[n]) self.add_text(['";', '\n']) for n in node.childNodes: if n not in first.values(): self.parse(n) elif kind in ('file', 'namespace'): nodes = node.getElementsByTagName('sectiondef') for n in nodes: self.parse(n) def do_includes(self, node): self.add_text('C++ includes: ') self.generic_parse(node, pad=1) def do_parameterlist(self, node): text = 'unknown' for key, val in node.attributes.items(): if key == 'kind': if val == 'param': text = 'Parameters' elif val == 'exception': text = 'Exceptions' elif val == 'retval': text = 'Returns' else: text = val break self.add_text(['\n', '\n', text, ':', '\n']) self.generic_parse(node, pad=1) def do_para(self, node): self.add_text('\n') self.generic_parse(node, pad=1) def do_parametername(self, node): self.add_text('\n') try: data = node.firstChild.data except AttributeError: # perhaps a <ref> tag in it data = node.firstChild.firstChild.data if data.find('Exception') != -1: self.add_text(data) else: self.add_text("%s: " % data) def do_parameterdefinition(self, node): self.generic_parse(node, pad=1) def do_detaileddescription(self, node): self.generic_parse(node, pad=1) def do_briefdescription(self, node): self.generic_parse(node, pad=1) def do_memberdef(self, node): prot = node.attributes['prot'].value id = node.attributes['id'].value kind = node.attributes['kind'].value tmp = node.parentNode.parentNode.parentNode compdef = tmp.getElementsByTagName('compounddef')[0] cdef_kind = compdef.attributes['kind'].value if prot == 'public': first = self.get_specific_nodes(node, ('definition', 'name')) name = first['name'].firstChild.data if name[:8] == 'operator': # Don't handle operators yet. return if not 'definition' in first or \ kind in ['variable', 'typedef']: return if self.include_function_definition: defn = first['definition'].firstChild.data else: defn = "" self.add_text('\n') self.add_text('%feature("docstring") ') anc = node.parentNode.parentNode if cdef_kind in ('file', 'namespace'): ns_node = anc.getElementsByTagName('innernamespace') if not ns_node and cdef_kind == 'namespace': ns_node = anc.getElementsByTagName('compoundname') if ns_node: ns = ns_node[0].firstChild.data self.add_text(' %s::%s "\n%s' % (ns, name, defn)) else: self.add_text(' %s "\n%s' % (name, defn)) elif cdef_kind in ('class', 'struct'): # Get the full function name. anc_node = anc.getElementsByTagName('compoundname') cname = anc_node[0].firstChild.data self.add_text(' %s::%s "\n%s' % (cname, name, defn)) for n in node.childNodes: if n not in first.values(): self.parse(n) self.add_text(['";', '\n']) def do_definition(self, node): data = node.firstChild.data self.add_text('%s "\n%s' % (data, data)) def do_sectiondef(self, node): kind = node.attributes['kind'].value if kind in ('public-func', 'func', 'user-defined', ''): self.generic_parse(node) def do_header(self, node): """For a user defined section def a header field is present which should not be printed as such, so we comment it in the output.""" data = node.firstChild.data self.add_text('\n/*\n %s \n*/\n' % data) # If our immediate sibling is a 'description' node then we # should comment that out also and remove it from the parent # node's children. parent = node.parentNode idx = parent.childNodes.index(node) if len(parent.childNodes) >= idx + 2: nd = parent.childNodes[idx + 2] if nd.nodeName == 'description': nd = parent.removeChild(nd) self.add_text('\n/*') self.generic_parse(nd) self.add_text('\n*/\n') def do_simplesect(self, node): kind = node.attributes['kind'].value if kind in ('date', 'rcs', 'version'): pass elif kind == 'warning': self.add_text(['\n', 'WARNING: ']) self.generic_parse(node) elif kind == 'see': self.add_text('\n') self.add_text('See: ') self.generic_parse(node) else: self.generic_parse(node) def do_argsstring(self, node): self.generic_parse(node, pad=1) def do_member(self, node): kind = node.attributes['kind'].value refid = node.attributes['refid'].value if kind == 'function' and refid[:9] == 'namespace': self.generic_parse(node) def do_doxygenindex(self, node): self.multi = 1 comps = node.getElementsByTagName('compound') for c in comps: refid = c.attributes['refid'].value fname = refid + '.xml' if not os.path.exists(fname): fname = os.path.join(self.my_dir, fname) if not self.quiet: print("parsing file: %s" % fname) p = Doxy2SWIG(fname, self.include_function_definition, self.quiet) p.generate() self.pieces.extend(self.clean_pieces(p.pieces)) def write(self, fname): o = my_open_write(fname) if self.multi: o.write("".join(x.encode('utf-8') for x in self.pieces)) else: o.write("".join(self.clean_pieces(self.pieces))) o.close() def clean_pieces(self, pieces): """Cleans the list of strings given as `pieces`. It replaces multiple newlines by a maximum of 2 and returns a new list. It also wraps the paragraphs nicely. """ ret = [] count = 0 for i in pieces: if i == '\n': count = count + 1 else: if i == '";': if count: ret.append('\n') elif count > 2: ret.append('\n\n') elif count: ret.append('\n' * count) count = 0 ret.append(i) _data = "".join(ret) ret = [] for i in _data.split('\n\n'): if i == 'Parameters:' or i == 'Exceptions:' or i == 'Returns:': ret.extend([i, '\n' + '-' * len(i), '\n\n']) elif i.find('// File:') > -1: # leave comments alone. ret.extend([i, '\n']) else: _tmp = textwrap.fill(i.strip(), break_long_words=False) _tmp = self.lead_spc.sub(r'\1"\2', _tmp) ret.extend([_tmp, '\n\n']) return ret def convert(input, output, include_function_definition=True, quiet=False): p = Doxy2SWIG(input, include_function_definition, quiet) p.generate() p.write(output) def main(): usage = __doc__ parser = optparse.OptionParser(usage) parser.add_option("-n", '--no-function-definition', action='store_true', default=False, dest='func_def', help='do not include doxygen function definitions') parser.add_option("-q", '--quiet', action='store_true', default=False, dest='quiet', help='be quiet and minimize output') options, args = parser.parse_args() if len(args) != 2: parser.error("error: no input and output specified") convert(args[0], args[1], not options.func_def, options.quiet) if __name__ == '__main__': main()