doc_status.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450
  1. #!/usr/bin/env python3
  2. import fnmatch
  3. import os
  4. import sys
  5. import re
  6. import math
  7. import platform
  8. import xml.etree.ElementTree as ET
  9. ################################################################################
  10. # Config #
  11. ################################################################################
  12. flags = {
  13. 'c': platform.platform() != 'Windows', # Disable by default on windows, since we use ANSI escape codes
  14. 'b': False,
  15. 'g': False,
  16. 's': False,
  17. 'u': False,
  18. 'h': False,
  19. 'p': False,
  20. 'o': True,
  21. 'i': False,
  22. 'a': True,
  23. }
  24. flag_descriptions = {
  25. 'c': 'Toggle colors when outputting.',
  26. 'b': 'Toggle showing only not fully described classes.',
  27. 'g': 'Toggle showing only completed classes.',
  28. 's': 'Toggle showing comments about the status.',
  29. 'u': 'Toggle URLs to docs.',
  30. 'h': 'Show help and exit.',
  31. 'p': 'Toggle showing percentage as well as counts.',
  32. 'o': 'Toggle overall column.',
  33. 'i': 'Toggle collapse of class items columns.',
  34. 'a': 'Toggle showing all items.',
  35. }
  36. long_flags = {
  37. 'colors': 'c',
  38. 'use-colors': 'c',
  39. 'bad': 'b',
  40. 'only-bad': 'b',
  41. 'good': 'g',
  42. 'only-good': 'g',
  43. 'comments': 's',
  44. 'status': 's',
  45. 'urls': 'u',
  46. 'gen-url': 'u',
  47. 'help': 'h',
  48. 'percent': 'p',
  49. 'use-percentages': 'p',
  50. 'overall': 'o',
  51. 'use-overall': 'o',
  52. 'items': 'i',
  53. 'collapse': 'i',
  54. 'all': 'a',
  55. }
  56. table_columns = ['name', 'brief_description', 'description', 'methods', 'constants', 'members', 'signals']
  57. table_column_names = ['Name', 'Brief Desc.', 'Desc.', 'Methods', 'Constants', 'Members', 'Signals']
  58. colors = {
  59. 'name': [36], # cyan
  60. 'part_big_problem': [4, 31], # underline, red
  61. 'part_problem': [31], # red
  62. 'part_mostly_good': [33], # yellow
  63. 'part_good': [32], # green
  64. 'url': [4, 34], # underline, blue
  65. 'section': [1, 4], # bold, underline
  66. 'state_off': [36], # cyan
  67. 'state_on': [1, 35], # bold, magenta/plum
  68. }
  69. overall_progress_description_weigth = 10
  70. ################################################################################
  71. # Utils #
  72. ################################################################################
  73. def validate_tag(elem, tag):
  74. if elem.tag != tag:
  75. print('Tag mismatch, expected "' + tag + '", got ' + elem.tag)
  76. sys.exit(255)
  77. def color(color, string):
  78. if flags['c']:
  79. color_format = ''
  80. for code in colors[color]:
  81. color_format += '\033[' + str(code) + 'm'
  82. return color_format + string + '\033[0m'
  83. else:
  84. return string
  85. ansi_escape = re.compile(r'\x1b[^m]*m')
  86. def nonescape_len(s):
  87. return len(ansi_escape.sub('', s))
  88. ################################################################################
  89. # Classes #
  90. ################################################################################
  91. class ClassStatusProgress:
  92. def __init__(self, described=0, total=0):
  93. self.described = described
  94. self.total = total
  95. def __add__(self, other):
  96. return ClassStatusProgress(self.described + other.described, self.total + other.total)
  97. def increment(self, described):
  98. if described:
  99. self.described += 1
  100. self.total += 1
  101. def is_ok(self):
  102. return self.described >= self.total
  103. def to_configured_colored_string(self):
  104. if flags['p']:
  105. return self.to_colored_string('{percent}% ({has}/{total})', '{pad_percent}{pad_described}{s}{pad_total}')
  106. else:
  107. return self.to_colored_string()
  108. def to_colored_string(self, format='{has}/{total}', pad_format='{pad_described}{s}{pad_total}'):
  109. ratio = self.described / self.total if self.total != 0 else 1
  110. percent = round(100 * ratio)
  111. s = format.format(has=str(self.described), total=str(self.total), percent=str(percent))
  112. if self.described >= self.total:
  113. s = color('part_good', s)
  114. elif self.described >= self.total / 4 * 3:
  115. s = color('part_mostly_good', s)
  116. elif self.described > 0:
  117. s = color('part_problem', s)
  118. else:
  119. s = color('part_big_problem', s)
  120. pad_size = max(len(str(self.described)), len(str(self.total)))
  121. pad_described = ''.ljust(pad_size - len(str(self.described)))
  122. pad_percent = ''.ljust(3 - len(str(percent)))
  123. pad_total = ''.ljust(pad_size - len(str(self.total)))
  124. return pad_format.format(pad_described=pad_described, pad_total=pad_total, pad_percent=pad_percent, s=s)
  125. class ClassStatus:
  126. def __init__(self, name=''):
  127. self.name = name
  128. self.has_brief_description = True
  129. self.has_description = True
  130. self.progresses = {
  131. 'methods': ClassStatusProgress(),
  132. 'constants': ClassStatusProgress(),
  133. 'members': ClassStatusProgress(),
  134. 'signals': ClassStatusProgress()
  135. }
  136. def __add__(self, other):
  137. new_status = ClassStatus()
  138. new_status.name = self.name
  139. new_status.has_brief_description = self.has_brief_description and other.has_brief_description
  140. new_status.has_description = self.has_description and other.has_description
  141. for k in self.progresses:
  142. new_status.progresses[k] = self.progresses[k] + other.progresses[k]
  143. return new_status
  144. def is_ok(self):
  145. ok = True
  146. ok = ok and self.has_brief_description
  147. ok = ok and self.has_description
  148. for k in self.progresses:
  149. ok = ok and self.progresses[k].is_ok()
  150. return ok
  151. def make_output(self):
  152. output = {}
  153. output['name'] = color('name', self.name)
  154. ok_string = color('part_good', 'OK')
  155. missing_string = color('part_big_problem', 'MISSING')
  156. output['brief_description'] = ok_string if self.has_brief_description else missing_string
  157. output['description'] = ok_string if self.has_description else missing_string
  158. description_progress = ClassStatusProgress(
  159. (self.has_brief_description + self.has_description) * overall_progress_description_weigth,
  160. 2 * overall_progress_description_weigth
  161. )
  162. items_progress = ClassStatusProgress()
  163. for k in ['methods', 'constants', 'members', 'signals']:
  164. items_progress += self.progresses[k]
  165. output[k] = self.progresses[k].to_configured_colored_string()
  166. output['items'] = items_progress.to_configured_colored_string()
  167. output['overall'] = (description_progress + items_progress).to_colored_string('{percent}%', '{pad_percent}{s}')
  168. if self.name.startswith('Total'):
  169. output['url'] = color('url', 'http://docs.godotengine.org/en/latest/classes/')
  170. if flags['s']:
  171. output['comment'] = color('part_good', 'ALL OK')
  172. else:
  173. output['url'] = color('url', 'http://docs.godotengine.org/en/latest/classes/class_{name}.html'.format(name=self.name.lower()))
  174. if flags['s'] and not flags['g'] and self.is_ok():
  175. output['comment'] = color('part_good', 'ALL OK')
  176. return output
  177. def generate_for_class(c):
  178. status = ClassStatus()
  179. status.name = c.attrib['name']
  180. # setgets do not count
  181. methods = []
  182. for tag in list(c):
  183. if tag.tag in ['methods']:
  184. for sub_tag in list(tag):
  185. methods.append(sub_tag.find('name'))
  186. if tag.tag in ['members']:
  187. for sub_tag in list(tag):
  188. try:
  189. methods.remove(sub_tag.find('setter'))
  190. methods.remove(sub_tag.find('getter'))
  191. except:
  192. pass
  193. for tag in list(c):
  194. if tag.tag == 'brief_description':
  195. status.has_brief_description = len(tag.text.strip()) > 0
  196. elif tag.tag == 'description':
  197. status.has_description = len(tag.text.strip()) > 0
  198. elif tag.tag in ['methods', 'signals']:
  199. for sub_tag in list(tag):
  200. if sub_tag.find('name') in methods or tag.tag == 'signals':
  201. descr = sub_tag.find('description')
  202. status.progresses[tag.tag].increment(len(descr.text.strip()) > 0)
  203. elif tag.tag in ['constants', 'members']:
  204. for sub_tag in list(tag):
  205. status.progresses[tag.tag].increment(len(sub_tag.text.strip()) > 0)
  206. elif tag.tag in ['theme_items']:
  207. pass # Ignore those tags, since they seem to lack description at all
  208. else:
  209. print(tag.tag, tag.attrib)
  210. return status
  211. ################################################################################
  212. # Arguments #
  213. ################################################################################
  214. input_file_list = []
  215. input_class_list = []
  216. merged_file = ""
  217. for arg in sys.argv[1:]:
  218. if arg.startswith('--'):
  219. flags[long_flags[arg[2:]]] = not flags[long_flags[arg[2:]]]
  220. elif arg.startswith('-'):
  221. for f in arg[1:]:
  222. flags[f] = not flags[f]
  223. elif os.path.isdir(arg):
  224. for f in os.listdir(arg):
  225. if f.endswith('.xml'):
  226. input_file_list.append(os.path.join(arg, f));
  227. else:
  228. input_class_list.append(arg)
  229. if flags['i']:
  230. for r in ['methods', 'constants', 'members', 'signals']:
  231. index = table_columns.index(r)
  232. del table_column_names[index]
  233. del table_columns[index]
  234. table_column_names.append('Items')
  235. table_columns.append('items')
  236. if flags['o'] == (not flags['i']):
  237. table_column_names.append('Overall')
  238. table_columns.append('overall')
  239. if flags['u']:
  240. table_column_names.append('Docs URL')
  241. table_columns.append('url')
  242. ################################################################################
  243. # Help #
  244. ################################################################################
  245. if len(input_file_list) < 1 or flags['h']:
  246. if not flags['h']:
  247. print(color('section', 'Invalid usage') + ': Please specify a classes directory')
  248. print(color('section', 'Usage') + ': doc_status.py [flags] <classes_dir> [class names]')
  249. print('\t< and > signify required parameters, while [ and ] signify optional parameters.')
  250. print(color('section', 'Available flags') + ':')
  251. possible_synonym_list = list(long_flags)
  252. possible_synonym_list.sort()
  253. flag_list = list(flags)
  254. flag_list.sort()
  255. for flag in flag_list:
  256. synonyms = [color('name', '-' + flag)]
  257. for synonym in possible_synonym_list:
  258. if long_flags[synonym] == flag:
  259. synonyms.append(color('name', '--' + synonym))
  260. print(('{synonyms} (Currently ' + color('state_' + ('on' if flags[flag] else 'off'), '{value}') + ')\n\t{description}').format(
  261. synonyms=', '.join(synonyms),
  262. value=('on' if flags[flag] else 'off'),
  263. description=flag_descriptions[flag]
  264. ))
  265. sys.exit(0)
  266. ################################################################################
  267. # Parse class list #
  268. ################################################################################
  269. class_names = []
  270. classes = {}
  271. for file in input_file_list:
  272. tree = ET.parse(file)
  273. doc = tree.getroot()
  274. if 'version' not in doc.attrib:
  275. print('Version missing from "doc"')
  276. sys.exit(255)
  277. version = doc.attrib['version']
  278. if doc.attrib['name'] in class_names:
  279. continue
  280. class_names.append(doc.attrib['name'])
  281. classes[doc.attrib['name']] = doc
  282. class_names.sort()
  283. if len(input_class_list) < 1:
  284. input_class_list = ['*']
  285. filtered_classes = set()
  286. for pattern in input_class_list:
  287. filtered_classes |= set(fnmatch.filter(class_names, pattern))
  288. filtered_classes = list(filtered_classes)
  289. filtered_classes.sort()
  290. ################################################################################
  291. # Make output table #
  292. ################################################################################
  293. table = [table_column_names]
  294. table_row_chars = '+- '
  295. table_column_chars = '|'
  296. total_status = ClassStatus('Total')
  297. for cn in filtered_classes:
  298. c = classes[cn]
  299. validate_tag(c, 'class')
  300. status = ClassStatus.generate_for_class(c)
  301. total_status = total_status + status
  302. if (flags['b'] and status.is_ok()) or (flags['g'] and not status.is_ok()) or (not flags['a']):
  303. continue
  304. out = status.make_output()
  305. row = []
  306. for column in table_columns:
  307. if column in out:
  308. row.append(out[column])
  309. else:
  310. row.append('')
  311. if 'comment' in out and out['comment'] != '':
  312. row.append(out['comment'])
  313. table.append(row)
  314. ################################################################################
  315. # Print output table #
  316. ################################################################################
  317. if len(table) == 1 and flags['a']:
  318. print(color('part_big_problem', 'No classes suitable for printing!'))
  319. sys.exit(0)
  320. if len(table) > 2 or not flags['a']:
  321. total_status.name = 'Total = {0}'.format(len(table) - 1)
  322. out = total_status.make_output()
  323. row = []
  324. for column in table_columns:
  325. if column in out:
  326. row.append(out[column])
  327. else:
  328. row.append('')
  329. table.append(row)
  330. table_column_sizes = []
  331. for row in table:
  332. for cell_i, cell in enumerate(row):
  333. if cell_i >= len(table_column_sizes):
  334. table_column_sizes.append(0)
  335. table_column_sizes[cell_i] = max(nonescape_len(cell), table_column_sizes[cell_i])
  336. divider_string = table_row_chars[0]
  337. for cell_i in range(len(table[0])):
  338. divider_string += table_row_chars[1] * (table_column_sizes[cell_i] + 2) + table_row_chars[0]
  339. print(divider_string)
  340. for row_i, row in enumerate(table):
  341. row_string = table_column_chars
  342. for cell_i, cell in enumerate(row):
  343. padding_needed = table_column_sizes[cell_i] - nonescape_len(cell) + 2
  344. if cell_i == 0:
  345. row_string += table_row_chars[2] + cell + table_row_chars[2] * (padding_needed - 1)
  346. else:
  347. row_string += table_row_chars[2] * math.floor(padding_needed / 2) + cell + table_row_chars[2] * math.ceil((padding_needed / 2))
  348. row_string += table_column_chars
  349. print(row_string)
  350. if row_i == 0 or row_i == len(table) - 2:
  351. print(divider_string)
  352. print(divider_string)
  353. if total_status.is_ok() and not flags['g']:
  354. print('All listed classes are ' + color('part_good', 'OK') + '!')