From ced40f803ec88e0de194aac9f4991cb0f7e30d77 Mon Sep 17 00:00:00 2001 From: Gbkng Date: Thu, 11 Apr 2024 13:59:03 +0200 Subject: [PATCH] style: reformat doxy2swig script --- doc/developer/doxygen/doxy2swig/doxy2swig.py | 270 ++++++++++--------- 1 file changed, 140 insertions(+), 130 deletions(-) diff --git a/doc/developer/doxygen/doxy2swig/doxy2swig.py b/doc/developer/doxygen/doxy2swig/doxy2swig.py index 6740ba9a0..00270cb5f 100755 --- a/doc/developer/doxygen/doxy2swig/doxy2swig.py +++ b/doc/developer/doxygen/doxy2swig/doxy2swig.py @@ -35,14 +35,15 @@ import textwrap import os.path import optparse -class Doxy2SWIG: + +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 @@ -52,15 +53,14 @@ class Doxy2SWIG: using %feature("autodoc", [0,1]). """ - with open(src, 'r') as f: + with open(src, "r") as f: self.my_dir = os.path.dirname(f.name) self.xmldoc = minidom.parse(f).documentElement self.pieces = [] - self.pieces.append('\n// File: %s\n'%\ - os.path.basename(f.name)) + self.pieces.append("\n// File: %s\n" % os.path.basename(f.name)) - self.space_re = re.compile(r'\s+') + 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 = [ @@ -83,28 +83,27 @@ class Doxy2SWIG: "derivedcompoundref", "basecompoundref", ] - + # self.generics = [] self.include_function_definition = include_function_definition if not include_function_definition: - self.ignores.append('argsstring') + 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_` functions which handle the respective nodes. """ - pm = getattr(self, "parse_%s"%node.__class__.__name__) + pm = getattr(self, "parse_%s" % node.__class__.__name__) pm(node) def parse_Document(self, node): @@ -112,8 +111,8 @@ class Doxy2SWIG: def parse_Text(self, node): txt = node.data - txt = txt.replace('\\', r'\\\\') - txt = txt.replace('"', r'\"') + 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): @@ -126,7 +125,7 @@ class Doxy2SWIG: `do_` 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 @@ -138,7 +137,7 @@ class Doxy2SWIG: handlerMethod(node) else: self.generic_parse(node) - #if name not in self.generics: self.generics.append(name) + # if name not in self.generics: self.generics.append(name) def parse_Comment(self, node): """Parse a `COMMENT_NODE`. This does nothing for now.""" @@ -157,9 +156,11 @@ class Doxy2SWIG: `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] + 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): @@ -180,15 +181,15 @@ class Doxy2SWIG: if pad: npiece = len(self.pieces) if pad == 2: - self.add_text('\n') + self.add_text("\n") for n in node.childNodes: self.parse(n) if pad: if len(self.pieces) > npiece: - self.add_text('\n') + self.add_text("\n") def space_parse(self, node): - self.add_text(' ') + self.add_text(" ") self.generic_parse(node) do_ref = space_parse @@ -198,60 +199,67 @@ class Doxy2SWIG: do_formula = space_parse def do_compoundname(self, node): - self.add_text('\n\n') + self.add_text("\n\n") data = node.firstChild.data - self.add_text('%%feature("docstring") %s "\n'%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': + kind = node.attributes["kind"].value + if kind in ("class", "struct"): + prot = node.attributes["prot"].value + if prot != "public": return - names = ('compoundname', 'briefdescription', - 'detaileddescription', 'includes') + names = ( + "compoundname", + "briefdescription", + "detaileddescription", + "includes", + ) first = self.get_specific_nodes(node, names) for n in names: if n in first: self.parse(first[n]) - self.add_text(['";','\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') + 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.add_text("C++ includes: ") self.generic_parse(node, pad=1) def do_parameterlist(self, node): - text='unknown' + text = "unknown" for key, val in node.attributes.items(): - if key == 'kind': - if val == 'param': text = 'Parameters' - elif val == 'exception': text = 'Exceptions' - else: text = val + if key == "kind": + if val == "param": + text = "Parameters" + elif val == "exception": + text = "Exceptions" + else: + text = val break - self.add_text(['\n', '\n', text, ':', '\n']) + self.add_text(["\n", "\n", text, ":", "\n"]) self.generic_parse(node, pad=1) def do_para(self, node): - self.add_text('\n') + self.add_text("\n") self.generic_parse(node, pad=1) def do_parametername(self, node): - self.add_text('\n') + self.add_text("\n") try: - data=node.firstChild.data - except AttributeError: # perhaps a tag in it - data=node.firstChild.firstChild.data - if data.find('Exception') != -1: + data = node.firstChild.data + except AttributeError: # perhaps a tag in it + data = node.firstChild.firstChild.data + if data.find("Exception") != -1: self.add_text(data) else: - self.add_text("%s: "%data) + self.add_text("%s: " % data) def do_parameterdefinition(self, node): self.generic_parse(node, pad=1) @@ -263,57 +271,56 @@ class Doxy2SWIG: self.generic_parse(node, pad=1) def do_memberdef(self, node): - prot = node.attributes['prot'].value - kind = node.attributes['kind'].value + prot = node.attributes["prot"].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. + 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 'definition' not in first or \ - kind in ['variable', 'typedef']: + if "definition" not in first or kind in ["variable", "typedef"]: return if self.include_function_definition: - defn = first['definition'].firstChild.data + defn = first["definition"].firstChild.data else: defn = "" - self.add_text('\n') + 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 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)) + 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'): + self.add_text(' %s "\n%s' % (name, defn)) + elif cdef_kind in ("class", "struct"): # Get the full function name. - anc_node = anc.getElementsByTagName('compoundname') + anc_node = anc.getElementsByTagName("compoundname") cname = anc_node[0].firstChild.data - self.add_text(' %s::%s "\n%s'%(cname, name, defn)) + 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']) - + self.add_text(['";', "\n"]) + def do_definition(self, node): data = node.firstChild.data - self.add_text('%s "\n%s'%(data, data)) + self.add_text('%s "\n%s' % (data, data)) def do_sectiondef(self, node): - kind = node.attributes['kind'].value - if kind in ('public-static-func', 'public-func', 'func', 'user-defined', ''): + kind = node.attributes["kind"].value + if kind in ("public-static-func", "public-func", "func", "user-defined", ""): self.generic_parse(node) def do_header(self, node): @@ -322,31 +329,32 @@ class Doxy2SWIG: output.""" data = node.firstChild.data self.add_text("\n/*\n %s \n*/\n" % data) - # If our immediate sibling is a 'description' node, we should comment - # that out also and remove it from the parent node's children. + # 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.childNodes[idx + 2] + if nd.nodeName == "description": nd = parent.removeChild(nd) - self.add_text('\n/*') + self.add_text("\n/*") self.generic_parse(nd) - self.add_text('\n*/\n') + self.add_text("\n*/\n") def do_simplesect(self, node): - kind = node.attributes['kind'].value - if kind in ('date', 'rcs', 'version'): + kind = node.attributes["kind"].value + if kind in ("date", "rcs", "version"): pass - elif kind == 'warning': - self.add_text(['\n', 'WARNING: ']) + elif kind == "warning": + self.add_text(["\n", "WARNING: "]) self.generic_parse(node) - elif kind == 'see': - self.add_text('\n') - self.add_text('See: ') + elif kind == "see": + self.add_text("\n") + self.add_text("See: ") self.generic_parse(node) - elif kind == 'return': - self.add_text(['\n', '===> Returns: ']) + elif kind == "return": + self.add_text(["\n", "===> Returns: "]) self.generic_parse(node) else: self.generic_parse(node) @@ -355,27 +363,27 @@ class Doxy2SWIG: 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': + 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') + comps = node.getElementsByTagName("compound") for c in comps: - refid = c.attributes['refid'].value - fname = refid + '.xml' + refid = c.attributes["refid"].value + fname = refid + ".xml" if not os.path.exists(fname): - fname = os.path.join(self.my_dir, fname) + fname = os.path.join(self.my_dir, fname) if not self.quiet: - print("parsing file: %s"%fname) + 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): - with open(fname, 'w') as o: + with open(fname, "w") as o: if self.multi: o.write("".join(self.pieces)) else: @@ -385,35 +393,35 @@ class Doxy2SWIG: """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': + if i == "\n": count = count + 1 else: if i == '";': if count: - ret.append('\n') + ret.append("\n") elif count > 2: - ret.append('\n\n') + ret.append("\n\n") elif count: - ret.append('\n'*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:': - ret.extend([i, '\n-----------', '\n\n']) - elif i.find('// File:') > -1: # leave comments alone. - ret.extend([i, '\n']) + for i in _data.split("\n\n"): + if i == "Parameters:" or i == "Exceptions:": + ret.extend([i, "\n-----------", "\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']) + ret.extend([_tmp, "\n\n"]) return ret @@ -422,31 +430,33 @@ def convert(input, output, include_function_definition=True, quiet=False): 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') - + 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( - input=args[0], - output=args[1], - include_function_definition=not options.func_def, - quiet=options.quiet, - ) + convert(args[0], args[1], not options.func_def, options.quiet) -if __name__ == '__main__': - main() +if __name__ == "__main__": + main() -- 2.39.2