]> SALOME platform Git repositories - modules/shaper.git/blob - scripts/doxy2swig.py
Salome HOME
Issue #3047: Rollback modifications dedicated to property panel performance
[modules/shaper.git] / scripts / doxy2swig.py
1 #!/usr/bin/env python3
2 """doxy2swig.py [options] index.xml output.i
3
4 Doxygen XML to SWIG docstring converter (improved version).
5
6 Converts Doxygen generated XML files into a file containing docstrings
7 for use by SWIG.
8
9 index.xml is your doxygen generated XML file and output.i is where the
10 output will be written (the file will be clobbered).
11 """
12 #
13 # The current version of this code is hosted on a github repository:
14 #   https://github.com/m7thon/doxy2swig
15 #
16 # This code is implemented using Mark Pilgrim's code as a guideline:
17 #   http://www.faqs.org/docs/diveintopython/kgp_divein.html
18 #
19 # Original Author: Prabhu Ramachandran
20 # Modified by:     Michael Thon (June 2015)
21 # License: BSD style
22 #
23 # Thanks:
24 #   Johan Hake:  the include_function_definition feature
25 #   Bill Spotz:  bug reports and testing.
26 #   Sebastian Henschel:   Misc. enhancements.
27 #
28 # Changes:
29 # June 2015 (Michael Thon):
30 #   - class documentation:
31 #     -c: add constructor call signatures and a "Constructors" section
32 #         collecting the respective docs (e.g. for python)
33 #     -a: add "Attributes" section collecting the documentation for member
34 #         variables (e.g. for python)
35 #   - overloaded functions:
36 #     -o: collect all documentation into one "Overloaded function" section
37 #   - option to include function definition / signature renamed to -f
38 #   - formatting:
39 #     + included function signatures slightly reformatted
40 #     + option (-t) to turn off/on type information for funciton signatures
41 #     + lists (incl. nested and ordered)
42 #     + attempt to produce docstrings that render nicely as markdown
43 #     + translate code, emphasis, bold, linebreak, hruler, blockquote,
44 #       verbatim, heading tags to markdown
45 #     + new text-wrapping and option -w to specify the text width
46 #
47
48 from xml.dom import minidom
49 import re
50 import textwrap
51 import sys
52 import os.path
53 import optparse
54
55
56 def my_open_read(source):
57     if hasattr(source, "read"):
58         return source
59     else:
60         try:
61             return open(source, encoding='utf-8')
62         except TypeError:
63             return open(source)
64
65 def my_open_write(dest):
66     if hasattr(dest, "write"):
67         return dest
68     else:
69         try:
70             return open(dest, 'w', encoding='utf-8')
71         except TypeError:
72             return open(dest, 'w')
73
74 # MARK: Text handling:
75 def shift(txt, indent = '    ', prepend = ''):
76     """Return a list corresponding to the lines of text in the `txt` list
77     indented by `indent`. Prepend instead the string given in `prepend` to the
78     beginning of the first line. Note that if len(prepend) > len(indent), then
79     `prepend` will be truncated (doing better is tricky!). This preserves a
80     special '' entry at the end of `txt` (see `do_para` for the meaning).
81     """
82     if type(indent) is int:
83         indent = indent * ' '
84     special_end = txt[-1:] == ['']
85     lines = ''.join(txt).splitlines(True)
86     for i in range(1,len(lines)):
87         if lines[i].strip() or indent.strip():
88             lines[i] = indent + lines[i]
89     if not lines:
90         return prepend
91     prepend = prepend[:len(indent)]
92     indent = indent[len(prepend):]
93     lines[0] = prepend + indent + lines[0]
94     ret = [''.join(lines)]
95     if special_end:
96         ret.append('')
97     return ret
98
99 class Doxy2SWIG:
100     """Converts Doxygen generated XML files into a file containing
101     docstrings that can be used by SWIG-1.3.x that have support for
102     feature("docstring").  Once the data is parsed it is stored in
103     self.pieces.
104
105     """
106
107     def __init__(self, src,
108                  with_function_signature = False,
109                  with_type_info = False,
110                  with_constructor_list = False,
111                  with_attribute_list = False,
112                  with_overloaded_functions = False,
113                  textwidth = 80,
114                  quiet = False):
115         """Initialize the instance given a source object.  `src` can
116         be a file or filename.  If you do not want to include function
117         definitions from doxygen then set
118         `include_function_definition` to `False`.  This is handy since
119         this allows you to use the swig generated function definition
120         using %feature("autodoc", [0,1]).
121
122         """
123         # options:
124         self.with_function_signature = with_function_signature
125         self.with_type_info = with_type_info
126         self.with_constructor_list = with_constructor_list
127         self.with_attribute_list = with_attribute_list
128         self.with_overloaded_functions = with_overloaded_functions
129         self.textwidth = textwidth
130         self.quiet = quiet
131
132         # state:
133         self.indent = 0
134         self.listitem = ''
135         self.pieces = []
136
137         f = my_open_read(src)
138         self.my_dir = os.path.dirname(f.name)
139         self.xmldoc = minidom.parse(f).documentElement
140         f.close()
141
142         self.pieces.append('\n// File: %s\n' %
143                            os.path.basename(f.name))
144
145         self.space_re = re.compile(r'\s+')
146         self.lead_spc = re.compile(r'^(%feature\S+\s+\S+\s*?)"\s+(\S)')
147         self.multi = 0
148         self.ignores = ['inheritancegraph', 'param', 'listofallmembers',
149                         'innerclass', 'name', 'declname', 'incdepgraph',
150                         'invincdepgraph', 'programlisting', 'type',
151                         'references', 'referencedby', 'location',
152                         'collaborationgraph', 'reimplements',
153                         'reimplementedby', 'derivedcompoundref',
154                         'basecompoundref',
155                         'argsstring', 'definition', 'exceptions']
156         #self.generics = []
157
158     def generate(self):
159         """Parses the file set in the initialization.  The resulting
160         data is stored in `self.pieces`.
161
162         """
163         self.parse(self.xmldoc)
164
165     def write(self, fname):
166         o = my_open_write(fname)
167         o.write(''.join(self.pieces))
168         o.write('\n')
169         o.close()
170
171     def parse(self, node):
172         """Parse a given node.  This function in turn calls the
173         `parse_<nodeType>` functions which handle the respective
174         nodes.
175
176         """
177         pm = getattr(self, "parse_%s" % node.__class__.__name__)
178         pm(node)
179
180     def parse_Document(self, node):
181         self.parse(node.documentElement)
182
183     def parse_Text(self, node):
184         txt = node.data
185         if txt == ' ':
186             # this can happen when two tags follow in a text, e.g.,
187             # " ...</emph> <formaula>$..." etc.
188             # here we want to keep the space.
189             self.add_text(txt)
190             return
191         txt = txt.replace('\\', r'\\')
192         txt = txt.replace('"', r'\"')
193         # ignore pure whitespace
194         m = self.space_re.match(txt)
195         if m and len(m.group()) == len(txt):
196             pass
197         else:
198             self.add_text(txt)
199
200     def parse_Comment(self, node):
201         """Parse a `COMMENT_NODE`.  This does nothing for now."""
202         return
203
204     def parse_Element(self, node):
205         """Parse an `ELEMENT_NODE`.  This calls specific
206         `do_<tagName>` handers for different elements.  If no handler
207         is available the `subnode_parse` method is called.  All
208         tagNames specified in `self.ignores` are simply ignored.
209
210         """
211         name = node.tagName
212         ignores = self.ignores
213         if name in ignores:
214             return
215         attr = "do_%s" % name
216         if hasattr(self, attr):
217             handlerMethod = getattr(self, attr)
218             handlerMethod(node)
219         else:
220             self.subnode_parse(node)
221             #if name not in self.generics: self.generics.append(name)
222
223 # MARK: Special format parsing
224     def subnode_parse(self, node, pieces=None, indent=0, ignore=[], restrict=None):
225         """Parse the subnodes of a given node. Subnodes with tags in the
226         `ignore` list are ignored. If pieces is given, use this as target for
227         the parse results instead of self.pieces. Indent all lines by the amount
228         given in `indent`. Note that the initial content in `pieces` is not
229         indented. The final result is in any case added to self.pieces."""
230         if pieces is not None:
231             old_pieces, self.pieces = self.pieces, pieces
232         else:
233             old_pieces = []
234         if type(indent) is int:
235             indent = indent * ' '
236         if len(indent) > 0:
237             pieces = ''.join(self.pieces)
238             i_piece = pieces[:len(indent)]
239             if self.pieces[-1:] == ['']:
240                 self.pieces = [pieces[len(indent):]] + ['']
241             elif self.pieces != []:
242                 self.pieces = [pieces[len(indent):]]
243         self.indent += len(indent)
244         for n in node.childNodes:
245             if restrict is not None:
246                 if n.nodeType == n.ELEMENT_NODE and n.tagName in restrict:
247                     self.parse(n)
248             elif n.nodeType != n.ELEMENT_NODE or n.tagName not in ignore:
249                 self.parse(n)
250         if len(indent) > 0:
251             self.pieces = shift(self.pieces, indent, i_piece)
252         self.indent -= len(indent)
253         old_pieces.extend(self.pieces)
254         self.pieces = old_pieces
255
256     def surround_parse(self, node, pre_char, post_char):
257         """Parse the subnodes of a given node. Subnodes with tags in the
258         `ignore` list are ignored. Prepend `pre_char` and append `post_char` to
259         the output in self.pieces."""
260         self.add_text(pre_char)
261         self.subnode_parse(node)
262         self.add_text(post_char)
263
264 # MARK: Helper functions
265     def get_specific_subnodes(self, node, name, recursive=0):
266         """Given a node and a name, return a list of child `ELEMENT_NODEs`, that
267         have a `tagName` matching the `name`. Search recursively for `recursive`
268         levels.
269         """
270         children = [x for x in node.childNodes if x.nodeType == x.ELEMENT_NODE]
271         ret = [x for x in children if x.tagName == name]
272         if recursive > 0:
273             for x in children:
274                 ret.extend(self.get_specific_subnodes(x, name, recursive-1))
275         return ret
276
277     def get_specific_nodes(self, node, names):
278         """Given a node and a sequence of strings in `names`, return a
279         dictionary containing the names as keys and child
280         `ELEMENT_NODEs`, that have a `tagName` equal to the name.
281
282         """
283         nodes = [(x.tagName, x) for x in node.childNodes
284                  if x.nodeType == x.ELEMENT_NODE and
285                  x.tagName in names]
286         return dict(nodes)
287
288     def add_text(self, value):
289         """Adds text corresponding to `value` into `self.pieces`."""
290         if isinstance(value, (list, tuple)):
291             self.pieces.extend(value)
292         else:
293             self.pieces.append(value)
294
295     def start_new_paragraph(self):
296         """Make sure to create an empty line. This is overridden, if the previous
297         text ends with the special marker ''. In that case, nothing is done.
298         """
299         if self.pieces[-1:] == ['']: # respect special marker
300             return
301         elif self.pieces == []: # first paragraph, add '\n', override with ''
302             self.pieces = ['\n']
303         elif self.pieces[-1][-1:] != '\n': # previous line not ended
304             self.pieces.extend(['  \n' ,'\n'])
305         else: #default
306             self.pieces.append('\n')
307
308     def add_line_with_subsequent_indent(self, line, indent=4):
309         """Add line of text and wrap such that subsequent lines are indented
310         by `indent` spaces.
311         """
312         if isinstance(line, (list, tuple)):
313             line = ''.join(line)
314         line = line.strip()
315         width = self.textwidth-self.indent-indent
316         wrapped_lines = textwrap.wrap(line[indent:], width=width)
317         for i in range(len(wrapped_lines)):
318             if wrapped_lines[i] != '':
319                 wrapped_lines[i] = indent * ' ' + wrapped_lines[i]
320         self.pieces.append(line[:indent] + '\n'.join(wrapped_lines)[indent:] + '  \n')
321
322     def extract_text(self, node):
323         """Return the string representation of the node or list of nodes by parsing the
324         subnodes, but returning the result as a string instead of adding it to `self.pieces`.
325         Note that this allows extracting text even if the node is in the ignore list.
326         """
327         if not isinstance(node, (list, tuple)):
328             node = [node]
329         pieces, self.pieces = self.pieces, ['']
330         for n in node:
331             for sn in n.childNodes:
332                 self.parse(sn)
333         ret = ''.join(self.pieces)
334         self.pieces = pieces
335         return ret
336
337     def get_function_signature(self, node):
338         """Returns the function signature string for memberdef nodes."""
339         name = self.extract_text(self.get_specific_subnodes(node, 'name'))
340         if self.with_type_info:
341             argsstring = self.extract_text(self.get_specific_subnodes(node, 'argsstring'))
342         else:
343             argsstring = []
344             param_id = 1
345             for n_param in self.get_specific_subnodes(node, 'param'):
346                 declname = self.extract_text(self.get_specific_subnodes(n_param, 'declname'))
347                 if not declname:
348                     declname = 'arg' + str(param_id)
349                 defval = self.extract_text(self.get_specific_subnodes(n_param, 'defval'))
350                 if defval:
351                     defval = '=' + defval
352                 argsstring.append(declname + defval)
353                 param_id = param_id + 1
354             argsstring = '(' + ', '.join(argsstring) + ')'
355         type = self.extract_text(self.get_specific_subnodes(node, 'type'))
356         function_definition = name + argsstring
357         if type != '' and type != 'void':
358             function_definition = function_definition + ' -> ' + type
359         return '`' + function_definition + '`  '
360
361 # MARK: Special parsing tasks (need to be called manually)
362     def make_constructor_list(self, constructor_nodes, classname):
363         """Produces the "Constructors" section and the constructor signatures
364         (since swig does not do so for classes) for class docstrings."""
365         if constructor_nodes == []:
366             return
367         self.add_text(['\n', 'Constructors',
368                        '\n', '------------'])
369         for n in constructor_nodes:
370             self.add_text('\n')
371             self.add_line_with_subsequent_indent('* ' + self.get_function_signature(n))
372             self.subnode_parse(n, pieces = [], indent=4, ignore=['definition', 'name'])
373
374     def make_attribute_list(self, node):
375         """Produces the "Attributes" section in class docstrings for public
376         member variables (attributes).
377         """
378         atr_nodes = []
379         for n in self.get_specific_subnodes(node, 'memberdef', recursive=2):
380             if n.attributes['kind'].value == 'variable' and n.attributes['prot'].value == 'public':
381                 atr_nodes.append(n)
382         if not atr_nodes:
383             return
384         self.add_text(['\n', 'Attributes',
385                        '\n', '----------'])
386         for n in atr_nodes:
387             name = self.extract_text(self.get_specific_subnodes(n, 'name'))
388             self.add_text(['\n* ', '`', name, '`', ' : '])
389             self.add_text(['`', self.extract_text(self.get_specific_subnodes(n, 'type')), '`'])
390             self.add_text('  \n')
391             restrict = ['briefdescription', 'detaileddescription']
392             self.subnode_parse(n, pieces=[''], indent=4, restrict=restrict)
393
394     def get_memberdef_nodes_and_signatures(self, node, kind):
395         """Collects the memberdef nodes and corresponding signatures that
396         correspond to public function entries that are at most depth 2 deeper
397         than the current (compounddef) node. Returns a dictionary with
398         function signatures (what swig expects after the %feature directive)
399         as keys, and a list of corresponding memberdef nodes as values."""
400         sig_dict = {}
401         sig_prefix = ''
402         if kind in ('file', 'namespace'):
403             ns_node = node.getElementsByTagName('innernamespace')
404             if not ns_node and kind == 'namespace':
405                 ns_node = node.getElementsByTagName('compoundname')
406             if ns_node:
407                 sig_prefix = self.extract_text(ns_node[0]) + '::'
408         elif kind in ('class', 'struct'):
409             # Get the full function name.
410             cn_node = node.getElementsByTagName('compoundname')
411             sig_prefix = self.extract_text(cn_node[0]) + '::'
412
413         md_nodes = self.get_specific_subnodes(node, 'memberdef', recursive=2)
414         for n in md_nodes:
415             if n.attributes['prot'].value != 'public':
416                 continue
417             if n.attributes['kind'].value in ['variable', 'typedef']:
418                 continue
419             if not self.get_specific_subnodes(n, 'definition'):
420                 continue
421             name = self.extract_text(self.get_specific_subnodes(n, 'name'))
422             if name[:8] == 'operator':
423                 continue
424             sig = sig_prefix + name
425             if sig in sig_dict:
426                 sig_dict[sig].append(n)
427             else:
428                 sig_dict[sig] = [n]
429         return sig_dict
430
431     def handle_typical_memberdefs_no_overload(self, signature, memberdef_nodes):
432         """Produce standard documentation for memberdef_nodes."""
433         for n in memberdef_nodes:
434             self.add_text(['\n', '%feature("docstring") ', signature, ' "', '\n'])
435             if self.with_function_signature:
436                 self.add_line_with_subsequent_indent(self.get_function_signature(n))
437             self.subnode_parse(n, pieces=[], ignore=['definition', 'name'])
438             self.add_text(['";', '\n'])
439
440     def handle_typical_memberdefs(self, signature, memberdef_nodes):
441         """Produces docstring entries containing an "Overloaded function"
442         section with the documentation for each overload, if the function is
443         overloaded and self.with_overloaded_functions is set. Else, produce
444         normal documentation.
445         """
446         if len(memberdef_nodes) == 1 or not self.with_overloaded_functions:
447             self.handle_typical_memberdefs_no_overload(signature, memberdef_nodes)
448             return
449
450         self.add_text(['\n', '%feature("docstring") ', signature, ' "', '\n'])
451         if self.with_function_signature:
452             for n in memberdef_nodes:
453                 self.add_line_with_subsequent_indent(self.get_function_signature(n))
454         self.add_text('\n')
455         self.add_text(['Overloaded function', '\n',
456                        '-------------------'])
457         for n in memberdef_nodes:
458             self.add_text('\n')
459             self.add_line_with_subsequent_indent('* ' + self.get_function_signature(n))
460             self.subnode_parse(n, pieces=[], indent=4, ignore=['definition', 'name'])
461         self.add_text(['";', '\n'])
462
463
464 # MARK: Tag handlers
465     def do_linebreak(self, node):
466         self.add_text('  ')
467
468     def do_ndash(self, node):
469         self.add_text('--')
470
471     def do_mdash(self, node):
472         self.add_text('---')
473
474     def do_emphasis(self, node):
475         self.surround_parse(node, '*', '*')
476
477     def do_bold(self, node):
478         self.surround_parse(node, '**', '**')
479
480     def do_computeroutput(self, node):
481         self.surround_parse(node, '`', '`')
482
483     def do_heading(self, node):
484         self.start_new_paragraph()
485         pieces, self.pieces = self.pieces, ['']
486         level = int(node.attributes['level'].value)
487         self.subnode_parse(node)
488         if level == 1:
489             self.pieces.insert(0, '\n')
490             self.add_text(['\n', len(''.join(self.pieces).strip()) * '='])
491         elif level == 2:
492             self.add_text(['\n', len(''.join(self.pieces).strip()) * '-'])
493         elif level >= 3:
494             self.pieces.insert(0, level * '#' + ' ')
495         # make following text have no gap to the heading:
496         pieces.extend([''.join(self.pieces) + '  \n', ''])
497         self.pieces = pieces
498
499     def do_verbatim(self, node):
500         self.start_new_paragraph()
501         self.subnode_parse(node, pieces=[''], indent=4)
502
503     def do_blockquote(self, node):
504         self.start_new_paragraph()
505         self.subnode_parse(node, pieces=[''], indent='> ')
506
507     def do_hruler(self, node):
508         self.start_new_paragraph()
509         self.add_text('* * * * *  \n')
510
511     def do_includes(self, node):
512         self.add_text('\nC++ includes: ')
513         self.subnode_parse(node)
514         self.add_text('\n')
515
516 # MARK: Para tag handler
517     def do_para(self, node):
518         """This is the only place where text wrapping is automatically performed.
519         Generally, this function parses the node (locally), wraps the text, and
520         then adds the result to self.pieces. However, it may be convenient to
521         allow the previous content of self.pieces to be included in the text
522         wrapping. For this, use the following *convention*:
523         If self.pieces ends with '', treat the _previous_ entry as part of the
524         current paragraph. Else, insert new-line and start a new paragraph
525         and "wrapping context".
526         Paragraphs always end with '  \n', but if the parsed content ends with
527         the special symbol '', this is passed on.
528         """
529         if self.pieces[-1:] == ['']:
530             pieces, self.pieces = self.pieces[:-2], self.pieces[-2:-1]
531         else:
532             self.add_text('\n')
533             pieces, self.pieces = self.pieces, ['']
534         self.subnode_parse(node)
535         dont_end_paragraph = self.pieces[-1:] == ['']
536         # Now do the text wrapping:
537         width = self.textwidth - self.indent
538         wrapped_para = []
539         for line in ''.join(self.pieces).splitlines():
540             keep_markdown_newline = line[-2:] == '  '
541             w_line = textwrap.wrap(line, width=width, break_long_words=False)
542             if w_line == []:
543                 w_line = ['']
544             if keep_markdown_newline:
545                 w_line[-1] = w_line[-1] + '  '
546             for wl in w_line:
547                 wrapped_para.append(wl + '\n')
548         if wrapped_para:
549             if wrapped_para[-1][-3:] != '  \n':
550                 wrapped_para[-1] = wrapped_para[-1][:-1] + '  \n'
551             if dont_end_paragraph:
552                 wrapped_para.append('')
553         pieces.extend(wrapped_para)
554         self.pieces = pieces
555
556 # MARK: List tag handlers
557     def do_itemizedlist(self, node):
558         if self.listitem == '':
559             self.start_new_paragraph()
560         elif self.pieces != [] and self.pieces[-1:] != ['']:
561             self.add_text('\n')
562         listitem = self.listitem
563         if self.listitem in ['*', '-']:
564             self.listitem = '-'
565         else:
566             self.listitem = '*'
567         self.subnode_parse(node)
568         self.listitem = listitem
569
570     def do_orderedlist(self, node):
571         if self.listitem == '':
572             self.start_new_paragraph()
573         elif self.pieces != [] and self.pieces[-1:] != ['']:
574             self.add_text('\n')
575         listitem = self.listitem
576         self.listitem = 0
577         self.subnode_parse(node)
578         self.listitem = listitem
579
580     def do_listitem(self, node):
581         try:
582             self.listitem = int(self.listitem) + 1
583             item = str(self.listitem) + '. '
584         except:
585             item = str(self.listitem) + ' '
586         self.subnode_parse(node, item, indent=4)
587
588 # MARK: Parameter list tag handlers
589     def do_parameterlist(self, node):
590         self.start_new_paragraph()
591         text = 'unknown'
592         for key, val in node.attributes.items():
593             if key == 'kind':
594                 if val == 'param':
595                     text = 'Parameters'
596                 elif val == 'exception':
597                     text = 'Exceptions'
598                 elif val == 'retval':
599                     text = 'Returns'
600                 else:
601                     text = val
602                 break
603         if self.indent == 0:
604             self.add_text([text, '\n', len(text) * '-', '\n'])
605         else:
606             self.add_text([text, ':  \n'])
607         self.subnode_parse(node)
608
609     def do_parameteritem(self, node):
610         self.subnode_parse(node, pieces=['* ', ''])
611
612     def do_parameternamelist(self, node):
613         self.subnode_parse(node)
614         self.add_text([' :', '  \n'])
615
616     def do_parametername(self, node):
617         if self.pieces != [] and self.pieces != ['* ', '']:
618             self.add_text(', ')
619         data = self.extract_text(node)
620         self.add_text(['`', data, '`'])
621
622     def do_parameterdescription(self, node):
623         self.subnode_parse(node, pieces=[''], indent=4)
624
625 # MARK: Section tag handler
626     def do_simplesect(self, node):
627         kind = node.attributes['kind'].value
628         if kind in ('date', 'rcs', 'version'):
629             return
630         self.start_new_paragraph()
631         if kind == 'warning':
632             self.subnode_parse(node, pieces=['**Warning**: ',''], indent=4)
633         elif kind == 'see':
634             self.subnode_parse(node, pieces=['See also: ',''], indent=4)
635         elif kind == 'return':
636             if self.indent == 0:
637                 pieces = ['Returns', '\n', len('Returns') * '-', '\n', '']
638             else:
639                 pieces = ['Returns:', '\n', '']
640             self.subnode_parse(node, pieces=pieces)
641         else:
642             self.subnode_parse(node, pieces=[kind + ': ',''], indent=4)
643
644 # MARK: %feature("docstring") producing tag handlers
645     def do_compounddef(self, node):
646         """This produces %feature("docstring") entries for classes, and handles
647         class, namespace and file memberdef entries specially to allow for
648         overloaded functions. For other cases, passes parsing on to standard
649         handlers (which may produce unexpected results).
650         """
651         kind = node.attributes['kind'].value
652         if kind in ('class', 'struct'):
653             prot = node.attributes['prot'].value
654             if prot != 'public':
655                 return
656             self.add_text('\n\n')
657             classdefn = self.extract_text(self.get_specific_subnodes(node, 'compoundname'))
658             classname = classdefn.split('::')[-1]
659             self.add_text('%%feature("docstring") %s "\n' % classdefn)
660
661             if self.with_constructor_list:
662                 constructor_nodes = []
663                 for n in self.get_specific_subnodes(node, 'memberdef', recursive=2):
664                     if n.attributes['prot'].value == 'public':
665                         if self.extract_text(self.get_specific_subnodes(n, 'definition')) == classdefn + '::' + classname:
666                             constructor_nodes.append(n)
667                 for n in constructor_nodes:
668                     self.add_line_with_subsequent_indent(self.get_function_signature(n))
669
670             names = ('briefdescription','detaileddescription')
671             sub_dict = self.get_specific_nodes(node, names)
672             for n in ('briefdescription','detaileddescription'):
673                 if n in sub_dict:
674                     self.parse(sub_dict[n])
675             if self.with_constructor_list:
676                 self.make_constructor_list(constructor_nodes, classname)
677             if self.with_attribute_list:
678                 self.make_attribute_list(node)
679
680             sub_list = self.get_specific_subnodes(node, 'includes')
681             if sub_list:
682                 self.parse(sub_list[0])
683             self.add_text(['";', '\n'])
684
685             names = ['compoundname', 'briefdescription','detaileddescription', 'includes']
686             self.subnode_parse(node, ignore = names)
687
688         elif kind in ('file', 'namespace'):
689             nodes = node.getElementsByTagName('sectiondef')
690             for n in nodes:
691                 self.parse(n)
692
693         # now explicitely handle possibly overloaded member functions.
694         if kind in ['class', 'struct','file', 'namespace']:
695             md_nodes = self.get_memberdef_nodes_and_signatures(node, kind)
696             for sig in md_nodes:
697                 self.handle_typical_memberdefs(sig, md_nodes[sig])
698
699     def do_memberdef(self, node):
700         """Handle cases outside of class, struct, file or namespace. These are
701         now dealt with by `handle_overloaded_memberfunction`.
702         Do these even exist???
703         """
704         prot = node.attributes['prot'].value
705         id = node.attributes['id'].value
706         kind = node.attributes['kind'].value
707         tmp = node.parentNode.parentNode.parentNode
708         compdef = tmp.getElementsByTagName('compounddef')[0]
709         cdef_kind = compdef.attributes['kind'].value
710         if cdef_kind in ('file', 'namespace', 'class', 'struct'):
711             # These cases are now handled by `handle_typical_memberdefs`
712             return
713         if prot != 'public':
714             return
715         first = self.get_specific_nodes(node, ('definition', 'name'))
716         name = self.extract_text(first['name'])
717         if name[:8] == 'operator':  # Don't handle operators yet.
718             return
719         if not 'definition' in first or kind in ['variable', 'typedef']:
720             return
721
722         data = self.extract_text(first['definition'])
723         self.add_text('\n')
724         self.add_text(['/* where did this entry come from??? */', '\n'])
725         self.add_text('%feature("docstring") %s "\n%s' % (data, data))
726
727         for n in node.childNodes:
728             if n not in first.values():
729                 self.parse(n)
730         self.add_text(['";', '\n'])
731
732 # MARK: Entry tag handlers (dont print anything meaningful)
733     def do_sectiondef(self, node):
734         kind = node.attributes['kind'].value
735         if kind in ('public-func', 'func', 'user-defined', ''):
736             self.subnode_parse(node)
737
738     def do_header(self, node):
739         """For a user defined section def a header field is present
740         which should not be printed as such, so we comment it in the
741         output."""
742         data = self.extract_text(node)
743         self.add_text('\n/*\n %s \n*/\n' % data)
744         # If our immediate sibling is a 'description' node then we
745         # should comment that out also and remove it from the parent
746         # node's children.
747         parent = node.parentNode
748         idx = parent.childNodes.index(node)
749         if len(parent.childNodes) >= idx + 2:
750             nd = parent.childNodes[idx + 2]
751             if nd.nodeName == 'description':
752                 nd = parent.removeChild(nd)
753                 self.add_text('\n/*')
754                 self.subnode_parse(nd)
755                 self.add_text('\n*/\n')
756
757     def do_member(self, node):
758         kind = node.attributes['kind'].value
759         refid = node.attributes['refid'].value
760         if kind == 'function' and refid[:9] == 'namespace':
761             self.subnode_parse(node)
762
763     def do_doxygenindex(self, node):
764         self.multi = 1
765         comps = node.getElementsByTagName('compound')
766         for c in comps:
767             refid = c.attributes['refid'].value
768             fname = refid + '.xml'
769             if not os.path.exists(fname):
770                 fname = os.path.join(self.my_dir,  fname)
771             if not self.quiet:
772                 print("parsing file: %s" % fname)
773             p = Doxy2SWIG(fname,
774                           with_function_signature = self.with_function_signature,
775                           with_type_info = self.with_type_info,
776                           with_constructor_list = self.with_constructor_list,
777                           with_attribute_list = self.with_attribute_list,
778                           with_overloaded_functions = self.with_overloaded_functions,
779                           textwidth = self.textwidth,
780                           quiet = self.quiet)
781             p.generate()
782             self.pieces.extend(p.pieces)
783
784 # MARK: main
785 def main():
786     usage = __doc__
787     parser = optparse.OptionParser(usage)
788     parser.add_option("-f", '--function-signature',
789                       action='store_true',
790                       default=False,
791                       dest='f',
792                       help='include function signature in the documentation. This is handy when not using swig auto-generated function definitions %feature("autodoc", [0,1])')
793     parser.add_option("-t", '--type-info',
794                       action='store_true',
795                       default=False,
796                       dest='t',
797                       help='include type information for arguments in function signatures. This is similar to swig autodoc level 1')
798     parser.add_option("-c", '--constructor-list',
799                       action='store_true',
800                       default=False,
801                       dest='c',
802                       help='generate a constructor list for class documentation. Useful for target languages where the object construction should be documented in the class documentation.')
803     parser.add_option("-a", '--attribute-list',
804                       action='store_true',
805                       default=False,
806                       dest='a',
807                       help='generate an attributes list for class documentation. Useful for target languages where class attributes should be documented in the class documentation.')
808     parser.add_option("-o", '--overloaded-functions',
809                       action='store_true',
810                       default=False,
811                       dest='o',
812                       help='collect all documentation for overloaded functions. Useful for target languages that have no concept of overloaded functions, but also to avoid having to attach the correct docstring to each function overload manually')
813     parser.add_option("-w", '--width', type="int",
814                       action='store',
815                       dest='w',
816                       default=80,
817                       help='textwidth for wrapping (default: 80). Note that the generated lines may include 2 additional spaces (for markdown).')
818     parser.add_option("-q", '--quiet',
819                       action='store_true',
820                       default=False,
821                       dest='q',
822                       help='be quiet and minimize output')
823
824     options, args = parser.parse_args()
825     if len(args) != 2:
826         parser.error("no input and output specified")
827
828     p = Doxy2SWIG(args[0],
829                   with_function_signature = options.f,
830                   with_type_info = options.t,
831                   with_constructor_list = options.c,
832                   with_attribute_list = options.a,
833                   with_overloaded_functions = options.o,
834                   textwidth = options.w,
835                   quiet = options.q)
836     p.generate()
837     p.write(args[1])
838
839 if __name__ == '__main__':
840     main()