Debian Codegraph @

docs/gen-api-gtkdoc.py

raw
1 #!/usr/bin/env python
2 #
3 # Copyright 2015 The Geany contributors
4 # Copyright 2021 Collabora Ltd.
5 # @author George Kiagiadakis <[email protected]>
6 #
7 # This program is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 2 of the License, or
10 # (at your option) any later version.
11 #
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
16 #
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
20 # MA 02110-1301, USA.
21
22 import os
23 import sys
24 import re
25 from lxml import etree
26 from optparse import OptionParser
27
28
29 def normalize_text(s):
30 r"""
31 Normalizes whitespace in text.
32 >>> normalize_text("asd xxx")
33 'asd xxx'
34 >>> normalize_text(" asd\nxxx ")
35 'asd xxx'
36 """
37 return s.replace("\n", " ").strip()
38
39
40 CXX_NAMESPACE_RE = re.compile(r'[_a-zA-Z][_0-9a-zA-Z]*::')
41 def fix_definition(s):
42 """
43 Removes C++ name qualifications from some definitions.
44 For example:
45 >>> fix_definition("bool flag")
46 'bool flag'
47 >>> fix_definition("bool FooBar::flag")
48 'bool flag'
49 >>> fix_definition("void(* _GeanyObjectClass::project_open) (GKeyFile *keyfile)")
50 'void(* project_open) (GKeyFile *keyfile)'
51 """
52 return CXX_NAMESPACE_RE.sub(r"", s)
53
54
55 class AtDoc(object):
56 def __init__(self):
57 self.retval = None
58 self.since = ""
59 self.annot = []
60
61 def cb(self, type, str):
62 if (type == "param"):
63 words = str.split(" ", 2)
64 self.annot = []
65 elif (type == "return"):
66 self.annot = []
67 elif (type == "since"):
68 self.since = str.rstrip()
69 elif (type == "see"):
70 return "See " + str
71 elif type in ("a", "c") and str in ("NULL", "TRUE", "FALSE"):
72 return "%" + str
73 elif (type == "a"):
74 return "@" + str
75 else:
76 return str
77
78 return ""
79
80
81 class DoxygenProcess(object):
82 def __init__(self):
83 self.at = None
84
85 # http://stackoverflow.com/questions/4624062/get-all-text-inside-a-tag-in-lxml
86 @staticmethod
87 def stringify_children(node):
88 from lxml.etree import tostring
89 from itertools import chain
90 parts = ([node.text] +
91 list(chain(*([c.text, tostring(c).decode("utf-8"), c.tail] for c in node.getchildren()))) +
92 [node.tail])
93 # filter removes possible Nones in texts and tails
94 return "".join(filter(None, parts))
95
96 def get_program_listing(self, xml):
97 from lxml.etree import tostring
98 arr = ["", "|[<!-- language=\"C\" -->"]
99 for l in xml.getchildren():
100 if (l.tag == "codeline"):
101 # a codeline is of the form
102 # <highlight class="normal">GeanyDocument<sp/>*doc<sp/>=<sp/>...;</highlight>
103 # <sp/> tags must be replaced with spaces, then just use the text
104 h = l.find("highlight")
105 if h is not None:
106 html = tostring(h).decode("utf-8")
107 html = html.replace("<sp/>", " ")
108 arr.append(" " + tostring(etree.HTML(html), method="text").decode("utf-8"))
109 arr.append("]|")
110 return "\n".join(arr)
111
112 def join_annot(self):
113 s = " ".join(map(lambda x: "(%s)" % x, self.at.annot))
114 return s + ": " if s else ""
115
116 def process_element(self, xml):
117 self.at = AtDoc()
118 s = self.__process_element(xml)
119 return s
120
121 def get_extra(self):
122 return self.join_annot()
123
124 def get_return(self):
125 return self.at.retval
126
127 def get_since(self):
128 return self.at.since
129
130 def __process_element(self, xml):
131 s = ""
132
133 if xml.text and re.search(r'\S', xml.text):
134 s += xml.text
135 for n in xml.getchildren():
136 if n.tag == "emphasis":
137 s += self.at.cb("a", self.__process_element(n))
138 if n.tag == "computeroutput":
139 s += self.at.cb("c", self.__process_element(n))
140 if n.tag == "itemizedlist":
141 s += "\n" + self.__process_element(n)
142 if n.tag == "listitem":
143 s += " - " + self.__process_element(n)
144 if n.tag == "para":
145 p = self.__process_element(n)
146 if re.search(r'\S', p):
147 s += p + "\n"
148 if n.tag == "ref":
149 s += n.text if n.text else ""
150 if n.tag == "simplesect":
151 ss = self.at.cb(n.get("kind"), self.__process_element(n))
152 s += ss + "\n" if ss else ""
153 if n.tag == "programlisting":
154 s += self.get_program_listing(n)
155 if n.tag == "xrefsect":
156 s += self.__process_element(n)
157 if n.tag == "xreftitle":
158 s += self.__process_element(n) + ": "
159 if n.tag == "xrefdescription":
160 s += self.__process_element(n)
161 if n.tag == "ulink":
162 s += self.__process_element(n)
163 if n.tag == "linebreak":
164 s += "\n"
165 if n.tag == "ndash":
166 s += "--"
167 # workaround for doxygen bug #646002
168 if n.tag == "htmlonly":
169 s += ""
170 if n.tail:
171 if re.search(r'\S', n.tail):
172 s += n.tail
173 if n.tag.startswith("param"):
174 pass # parameters are handled separately in DoxyFunction::from_memberdef()
175 return s
176
177
178 class DoxyMember(object):
179 def __init__(self, name, brief, extra=""):
180 self.name = name
181 self.brief = brief
182 self.extra = extra
183
184
185 class DoxyElement(object):
186
187 def __init__(self, name, definition, **kwargs):
188 self.name = name
189 self.definition = definition
190 self.brief = kwargs.get('brief', "")
191 self.detail = kwargs.get('detail', "")
192 self.members = kwargs.get('members', [])
193 self.since = kwargs.get('since', "")
194 self.extra = kwargs.get('extra', "")
195 self.retval = kwargs.get('retval', None)
196
197 def is_documented(self):
198 return (normalize_text(self.brief) != "" or
199 normalize_text(self.detail) != "" or
200 normalize_text(self.since) != "")
201
202 def add_brief(self, xml):
203 proc = DoxygenProcess()
204 self.brief = proc.process_element(xml)
205 self.extra += proc.get_extra()
206
207 def add_detail(self, xml):
208 proc = DoxygenProcess()
209 self.detail = proc.process_element(xml)
210 self.extra += proc.get_extra()
211 self.since = proc.get_since()
212
213 def add_member(self, xml):
214 name = xml.find("name").text
215 proc = DoxygenProcess()
216 brief = proc.process_element(xml.find("briefdescription"))
217 # optional doxygen command output appears within <detaileddescription />
218 proc.process_element(xml.find("detaileddescription"))
219 self.members.append(DoxyMember(name, normalize_text(brief), proc.get_extra()))
220
221 def add_param(self, xml):
222 name = xml.find("parameternamelist").find("parametername").text
223 proc = DoxygenProcess()
224 brief = proc.process_element(xml.find("parameterdescription"))
225 self.members.append(DoxyMember(name, normalize_text(brief), proc.get_extra()))
226
227 def add_return(self, xml):
228 proc = DoxygenProcess()
229 brief = proc.process_element(xml)
230 self.retval = DoxyMember("ret", normalize_text(brief), proc.get_extra())
231
232 def to_gtkdoc(self):
233 s = []
234 s.append("/**")
235 s.append(" * %s: %s" % (self.name, self.extra))
236 for p in self.members:
237 s.append(" * @%s: %s %s" % (p.name, p.extra, p.brief))
238 s.append(" *")
239 s.append(" * %s" % self.brief.replace("\n", "\n * "))
240 s.append(" *")
241 s.append(" * %s" % self.detail.replace("\n", "\n * "))
242 s.append(" *")
243 if self.retval:
244 s.append(" * Returns: %s %s" % (self.retval.extra, self.retval.brief))
245 if self.since:
246 s.append(" *")
247 s.append(" * Since: %s" % self.since)
248 s.append(" */")
249 s.append("")
250 return "\n".join(s)
251
252
253 class DoxyTypedef(DoxyElement):
254 @staticmethod
255 def from_memberdef(xml):
256 name = xml.find("name").text
257 d = normalize_text(xml.find("definition").text)
258 d += ";"
259 return DoxyTypedef(name, d)
260
261
262 class DoxyEnum(DoxyElement):
263 @staticmethod
264 def from_memberdef(xml):
265 name = xml.find("name").text
266 d = "typedef enum {\n"
267 for member in xml.findall("enumvalue"):
268 v = member.find("initializer")
269 d += "\t%s%s,\n" % (member.find("name").text, " "+v.text if v is not None else "")
270 d += "} %s;\n" % name
271
272 e = DoxyEnum(name, d)
273 e.add_brief(xml.find("briefdescription"))
274 e.add_detail(xml.find("detaileddescription"))
275 for p in xml.findall("enumvalue"):
276 e.add_member(p)
277 return e
278
279
280 class DoxyStruct(DoxyElement):
281 @staticmethod
282 def from_compounddef(xml, typedefs=[]):
283 name = xml.find("compoundname").text
284 d = "struct %s {\n" % name
285 memberdefs = xml.xpath(".//sectiondef[@kind='public-attrib']/memberdef")
286 for p in memberdefs:
287 # workaround for struct members. g-ir-scanner can't properly map struct members
288 # (beginning with struct GeanyFoo) to the typedef and assigns a generic type for them
289 # thus we fix that up here and enforce usage of the typedef. These are written
290 # out first, before any struct definition, for this reason
291 # Exception: there are no typedefs for GeanyFooPrivate so skip those. Their exact
292 # type isn't needed anyway
293 s = fix_definition(p.find("definition").text).lstrip()
294 proc = DoxygenProcess()
295 brief = proc.process_element(p.find("briefdescription"))
296 private = (normalize_text(brief) == "")
297 words = s.split()
298 if (words[0] == "struct"):
299 if not (words[1].endswith("Private") or words[1].endswith("Private*")):
300 s = " ".join(words[1:])
301 d += "\t/*< %s >*/\n\t%s;\n" % ("private" if private else "public", s)
302
303 d += "};\n"
304 e = DoxyStruct(name, d)
305 e.add_brief(xml.find("briefdescription"))
306 e.add_detail(xml.find("detaileddescription"))
307 for p in memberdefs:
308 e.add_member(p)
309 return e
310
311
312 class DoxyFunction(DoxyElement):
313 @staticmethod
314 def from_memberdef(xml):
315 name = xml.find("name").text
316 d = normalize_text(xml.find("definition").text)
317 if ((xml.find("argsstring").text) is not None):
318 d += " " + xml.find("argsstring").text + ";"
319 d = normalize_text(d)
320
321 e = DoxyFunction(name, d)
322 if (xml.get("prot") == "private"):
323 e.extra = "(skip)"
324 e.add_brief(xml.find("briefdescription"))
325 e.add_detail(xml.find("detaileddescription"))
326 for p in xml.xpath(".//detaileddescription/*/parameterlist[@kind='param']/parameteritem"):
327 e.add_param(p)
328 x = xml.xpath(".//detaileddescription/*/simplesect[@kind='return']")
329 if (len(x) > 0):
330 e.add_return(x[0])
331 return e
332
333
334 class DoxyVariable(DoxyElement):
335 @staticmethod
336 def from_memberdef(xml):
337 name = xml.find("name").text
338 d = normalize_text(xml.find("definition").text)
339 d += ";"
340 e = DoxyVariable(name, d)
341 e.add_brief(xml.find("briefdescription"))
342 t = xml.find("type")
343 if t is not None:
344 typestr = "".join(t.itertext()).strip()
345 if typestr.startswith("const "):
346 typestr = typestr[6:]
347 e.type = "("+typestr+") "
348 else:
349 e.type = ""
350 v = xml.find("initializer")
351 e.value = v.text.replace("=","").replace("\n","") if v is not None else ""
352 return e
353 def to_gtkdoc(self):
354 s = super().to_gtkdoc()
355 # need this to get g-ir-scanner to recognize this as a constant
356 s += "#define "+self.name+" ("+self.type+self.value+")\n"
357 s += "#undef "+self.name+"\n"
358 return s
359
360
361 def main(args):
362 xml_dir = None
363 outfile = None
364
365 parser = OptionParser(usage="usage: %prog [options] XML_DIR")
366 parser.add_option("-o", "--output", metavar="FILE", help="Write output to FILE",
367 action="store", dest="outfile")
368 opts, args = parser.parse_args(args[1:])
369
370 xml_dir = args[0]
371
372 if not (os.path.exists(xml_dir)):
373 sys.stderr.write("invalid xml directory\n")
374 return 1
375
376 symbols = []
377 transform = etree.XSLT(etree.parse(os.path.join(xml_dir, "combine.xslt")))
378 doc = etree.parse(os.path.join(xml_dir, "index.xml"))
379 root = transform(doc)
380 h_files = root.xpath(".//compounddef[@kind='file']/compoundname[substring(.,string-length(.)-1)='.h']/..")
381
382 for f in h_files:
383 for n0 in f.xpath(".//*/memberdef[@kind='enum']"):
384 e = DoxyEnum.from_memberdef(n0)
385 symbols.append(e)
386
387 for n0 in root.xpath(".//compounddef[@kind='struct']"):
388 e = DoxyStruct.from_compounddef(n0)
389 symbols.append(e)
390
391 for n0 in root.xpath(".//compounddef[@kind='group']"):
392 for n1 in n0.xpath(".//*/memberdef[@kind='function']"):
393 e = DoxyFunction.from_memberdef(n1)
394 symbols.append(e)
395 for n1 in n0.xpath(".//*/memberdef[@kind='variable']"):
396 e = DoxyVariable.from_memberdef(n1)
397 symbols.append(e)
398
399 if (opts.outfile):
400 try:
401 outfile = open(opts.outfile, "w+")
402 except OSError as err:
403 sys.stderr.write("failed to open \"%s\" for writing (%s)\n" % (opts.outfile, err.strerror))
404 return 1
405 else:
406 outfile = sys.stdout
407
408 try:
409 outfile.write("/*\n * Automatically generated file - do not edit\n */\n\n")
410
411 for e in filter(lambda x: x.is_documented(), symbols):
412 outfile.write("\n")
413 outfile.write(e.to_gtkdoc())
414 outfile.write("\n")
415
416 except BrokenPipeError:
417 # probably piped to head or tail
418 return 0
419
420 return 0
421
422 if __name__ == "__main__":
423 sys.exit(main(sys.argv))