mirror of
https://github.com/eclipse/upm.git
synced 2025-03-15 04:57:30 +03:00
doxygen: fix doxygen generation and inital pydoc generation
Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>
This commit is contained in:
parent
21991e3598
commit
edf88ef6a7
@ -1,9 +1,10 @@
|
||||
cmake_minimum_required (VERSION 2.8)
|
||||
project (upm)
|
||||
|
||||
set (SWIG_EXECUTABLE /usr/bin/swig)
|
||||
find_package (SWIG REQUIRED)
|
||||
include (${SWIG_USE_FILE})
|
||||
find_package (SWIG)
|
||||
if (SWIG_FOUND)
|
||||
include (${SWIG_USE_FILE})
|
||||
endif ()
|
||||
|
||||
find_package (PkgConfig REQUIRED)
|
||||
pkg_check_modules (MAA maa>=0.2.1)
|
||||
|
457
src/doxy2swig.py
Executable file
457
src/doxy2swig.py
Executable file
@ -0,0 +1,457 @@
|
||||
#!/usr/bin/env python
|
||||
"""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(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()
|
@ -1,22 +1,35 @@
|
||||
set (libname "hmc5883l")
|
||||
add_library (hmc5883l SHARED hmc5883l.cxx)
|
||||
|
||||
include_directories (${MAA_INCLUDE_DIR})
|
||||
|
||||
target_link_libraries (hmc5883l ${MAA_LIBRARIES})
|
||||
|
||||
find_package (PythonLibs)
|
||||
if (DOXYGEN_FOUND AND SWIG_FOUND)
|
||||
find_package (PythonLibs)
|
||||
|
||||
include_directories (
|
||||
${PYTHON_INCLUDE_PATH}
|
||||
${PYTHON_INCLUDE_DIRS}
|
||||
${MAA_INCLUDE_DIR}
|
||||
.
|
||||
)
|
||||
include_directories (
|
||||
${PYTHON_INCLUDE_PATH}
|
||||
${PYTHON_INCLUDE_DIRS}
|
||||
${MAA_INCLUDE_DIR}
|
||||
.
|
||||
)
|
||||
|
||||
set_source_files_properties (pyupm_hmc5883l.i PROPERTIES CPLUSPLUS ON)
|
||||
set_source_files_properties (jsupm_hmc5883l.i PROPERTIES CPLUSPLUS ON)
|
||||
set_source_files_properties (pyupm_hmc5883l.i PROPERTIES CPLUSPLUS ON)
|
||||
set_source_files_properties (jsupm_hmc5883l.i PROPERTIES CPLUSPLUS ON)
|
||||
|
||||
swig_add_module (pyupm_hmc5883l python pyupm_hmc5883l.i hmc5883l.cxx)
|
||||
swig_add_module (jsupm_hmc5883l python jsupm_hmc5883l.i hmc5883l.cxx)
|
||||
swig_link_libraries (pyupm_hmc5883l ${PYTHON_LIBRARIES} ${MAA_LIBRARIES})
|
||||
swig_link_libraries (jsupm_hmc5883l ${PYTHON_LIBRARIES} ${MAA_LIBRARIES})
|
||||
swig_add_module (pyupm_hmc5883l python pyupm_hmc5883l.i hmc5883l.cxx)
|
||||
swig_add_module (jsupm_hmc5883l python jsupm_hmc5883l.i hmc5883l.cxx)
|
||||
swig_link_libraries (pyupm_hmc5883l ${PYTHON_LIBRARIES} ${MAA_LIBRARIES})
|
||||
swig_link_libraries (jsupm_hmc5883l ${PYTHON_LIBRARIES} ${MAA_LIBRARIES})
|
||||
|
||||
set (CMAKE_SWIG_FLAGS -DDOXYGEN=${DOXYGEN_FOUND})
|
||||
add_custom_command (OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${libname}_doc.i
|
||||
COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../doxy2swig.py -n
|
||||
${CMAKE_BINARY_DIR}/xml/${libname}_8h.xml
|
||||
${CMAKE_CURRENT_BINARY_DIR}/${libname}_doc.i
|
||||
DEPENDS ${CMAKE_BINARY_DIR}/xml/${libname}_8h.xml
|
||||
)
|
||||
add_custom_target (${libname}doc_i DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${libname}_doc.i)
|
||||
add_dependencies (${libname}doc_i doc)
|
||||
add_dependencies (${SWIG_MODULE_pyupm_hmc5883l_REAL_NAME} ${libname}doc_i)
|
||||
|
||||
endif ()
|
||||
|
@ -1,7 +1,12 @@
|
||||
%module pyupm_hmc5883l
|
||||
|
||||
%feature("autodoc", "3");
|
||||
|
||||
#ifdef DOXYGEN
|
||||
%include "hmc5883l_doc.i"
|
||||
#endif
|
||||
|
||||
%include "hmc5883l.h"
|
||||
%{
|
||||
#include "hmc5883l.h"
|
||||
%}
|
||||
|
||||
%include "hmc5883l.h"
|
||||
|
Loading…
x
Reference in New Issue
Block a user