1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
import os
from system_utils import SystemUtils
class DoxygenExtractor:
md_special_chars =[
{
"md_char": "*",
"replacement": "*"
},
{
"md_char": "#",
"replacement": "#"
},
{
"md_char": "`",
"replacement": "·"
}
]
#constructor
def __init__(self, root, header_paths, working_dir = "./temp", doxygen_xml_dest = "./xml"):
os.chdir(root)
self.header_paths = header_paths
self.utils = SystemUtils()
self.doxygen_xml_dest = doxygen_xml_dest
self.working_dir = working_dir
###
# this function copies headers recursively from a source director to a destination
# directory.
###
def get_headers(self, from_dir, to_dir):
self.utils.copy_files(from_dir, to_dir, "*.h")
###
# Strips out reserved characters used in markdown notation, and replaces them
# with html character codes.
#
# @param text the text to strip and replace the md special characters
#
# @return the stripped text.
###
def escape_md_chars(self, text):
for char in self.md_special_chars:
text = text.replace(char['md_char'], "\\" + char['md_char'])
return text
###
# this function extracts data from an element tag ignoring the tag 'ref', but
# obtains the textual data it has inside the ref tag.
#
# @param element the element to process
#
# @return a list of extracted strings.
###
def extract_ignoring_refs(self, element):
list = []
if element.text is not None:
list.append(element.text)
for ref in element.iter(tag="ref"):
list.append(ref.text)
return list
###
# this function extracts data from an element tag including all sub elements
# (recursive)
#
# @param element the element to process
#
# @return a list of extracted strings.
###
def extract_with_subelements(self, element):
list = []
list.append(element.text or "")
#if element.text is not None:
#list.append(element.text)
for subelement in element:
if subelement is not None:
list = list + self.extract_with_subelements(subelement)
list.append(element.tail or "")
return list
###
# this function was at one point intended to fetch a value of a default parameter
# it is now only used to fetch the default parameters' name.
#
# @param document_root the root of the entire document
# @param element the element containing the default parameter
#
# @return a dictionary containing:
# {
# 'name':'',
# 'value':''
# }
#
# @note this would be more useful if it return the value, it currently does not.
###
def extract_default(self, element):
ref = element.find("ref")
return {'name':' '.join(element.itertext()), 'value':''}
###
# extracts a member function form the xml document
#
# @param root the document root
# @param xml_element the member function xml element.
#
# @return a function dictionary:
# {
# 'short_name':"",
# 'name':"",
# 'return_type':"",
# 'params':[],
# 'description':[],
# 'returns':"",
# 'notes':"",
# 'examples':""
# }
###
def extract_member_function(self, xml_element, function_filter = [], filter = True):
function = {
'short_name':"",
'name':"",
'return_type':"",
'params':[],
'description':[],
'returns':"",
'notes':"",
'examples':""
}
function['name'] = xml_element.find('definition').text
function['short_name'] = xml_element.find('name').text
if filter and any(filtered_func in function['short_name'] for filtered_func in function_filter):
print "Filtered out: " + function['short_name']
return
print "Generating documentation for: " + function['short_name']
if xml_element.find('type') is not None:
function['return_type'] = self.escape_md_chars(' '.join(self.extract_ignoring_refs(xml_element.find('type'))))
#extract our parameters for this member function
for parameter in xml_element.iter('param'):
type = ""
name = ""
if parameter.find('type') is not None:
type = self.escape_md_chars(' '.join(parameter.find('type').itertext()))
if parameter.find('declname') is not None:
name = ' '.join(self.extract_ignoring_refs(parameter.find('declname')))
param_object = {
'type': type,
'name': name,
'default':{
'name':"",
'value':""
}
}
if parameter.find('defval') is not None:
extracted = self.extract_default(parameter.find('defval'))
param_object['default']['name'] = extracted['name']
param_object['default']['value'] = extracted['value']
function['params'].append(param_object)
detailed_description = xml_element.find('detaileddescription')
if len(detailed_description.findall("para")) is not 0:
for para in detailed_description.findall("para"):
if len(para.findall("programlisting")) is 0 and len(para.findall("simplesect")) is 0:
function['description'] = function['description'] + self.extract_with_subelements(para)
#para indicates a new paragraph - we should treat it as such... append \n!
function['description'] = function['description'] + ["\n\n"]
if len(detailed_description.findall("para/simplesect[@kind='return']/para")) is not 0:
return_section = detailed_description.findall("para/simplesect[@kind='return']/para")[0]
function['returns'] = ' '.join(return_section.itertext())
if len(detailed_description.findall("para/simplesect[@kind='note']/para")) is not 0:
return_section = detailed_description.findall("para/simplesect[@kind='note']/para")[0]
function['notes'] = ' '.join(return_section.itertext())
examples = detailed_description.find('para/programlisting')
if examples is not None:
function['examples'] = ''.join([('' if index is 0 else ' ')+word for index, word in enumerate(examples.itertext(),1) ])
param_list = detailed_description.findall('para/parameterlist')
if len(param_list) is not 0:
for parameter_desc in param_list[0].findall('parameteritem'):
param_descriptor = {
'name':'',
'description':''
}
param_name = parameter_desc.findall('parameternamelist/parametername')
additional = parameter_desc.findall('parameterdescription/para')
if len(param_name) is not 0:
param_descriptor['name'] = param_name[0].text
if len(additional) is not 0:
param_descriptor['description'] = ' '.join(additional[0].itertext())
for descriptor in function['params']:
if param_descriptor['name'] in descriptor['name']:
descriptor['description'] = param_descriptor['description']
return function
def generate_doxygen(self):
self.utils.mk_dir(self.working_dir)
self.utils.clean_dir(self.working_dir)
for path in self.header_paths:
self.get_headers(path, self.working_dir)
if os.path.exists(self.doxygen_xml_dest):
self.utils.clean_dir(self.doxygen_xml_dest)
os.system('doxygen doxy-config.cfg')
|
