diff options
Diffstat (limited to 'doc')
| -rwxr-xr-x | doc/tools/doc_status.py | 430 |
1 files changed, 430 insertions, 0 deletions
diff --git a/doc/tools/doc_status.py b/doc/tools/doc_status.py new file mode 100755 index 0000000000..5faee570d8 --- /dev/null +++ b/doc/tools/doc_status.py @@ -0,0 +1,430 @@ +#!/usr/bin/python3 + +import sys +import re +import math +import platform +import xml.etree.ElementTree as ET + +################################################################################ +# Config # +################################################################################ + +flags = { + 'c': platform.platform() != 'Windows', # Disable by default on windows, since we use ANSI escape codes + 'b': False, + 'g': False, + 'u': False, + 'h': False, + 'p': False, + 'o': True, + 'i': False, +} +flag_descriptions = { + 'c': 'Toggle colors when outputting.', + 'b': 'Toggle showing only not fully described classes.', + 'g': 'Toggle showing only completed classes.', + 'u': 'Toggle URLs to docs.', + 'h': 'Show help and exit.', + 'p': 'Toggle showing percentage as well as counts.', + 'o': 'Toggle overall column.', + 'i': 'Toggle collapse of class items columns.', +} +long_flags = { + 'colors': 'c', + 'color': 'c', + 'use-colors': 'c', + + 'bad': 'b', + 'only-bad': 'b', + + 'good': 'g', + 'only-good': 'g', + + 'urls': 'u', + 'url': 'u', + 'generate-urls': 'u', + 'gen-url': 'u', + + 'help': 'h', + + 'percent': 'p', + 'percentages': 'p', + 'use-percentages': 'p', + + 'overall': 'o', + 'use-overall': 'o', + + 'items': 'i', + 'collapse-items': 'i', + 'collapse': 'i', + 'narrow': 'i', +} +table_columns = ['name', 'brief_description', 'description', 'methods', 'constants', 'members', 'signals'] +table_column_names = ['Name', 'Brief Description', 'Description', 'Methods', 'Constants', 'Members', 'Signals'] +colors = { + 'name': [34], # blue + 'part_big_problem': [4, 31], # underline, red + 'part_problem': [31], # red + 'part_mostly_good': [33], # yellow + 'part_good': [32], # green + 'url': [4, 34], # underline, blue + 'section': [1, 4], # bold, underline + 'state_off': [36], # cyan + 'state_on': [1, 35], # bold, magenta/plum +} +overall_progress_description_weigth = 10 + + + +################################################################################ +# Utils # +################################################################################ + +def validate_tag(elem, tag): + if elem.tag != tag: + print('Tag mismatch, expected "' + tag + '", got ' + elem.tag) + sys.exit(255) + +def color(color, string): + if flags['c']: + color_format = '' + for code in colors[color]: + color_format += '\033[' + str(code) + 'm' + return color_format + string + '\033[0m' + else: + return string + +ansi_escape = re.compile(r'\x1b[^m]*m') +def nonescape_len(s): + return len(ansi_escape.sub('', s)) + + + +################################################################################ +# Classes # +################################################################################ + +class ClassStatusProgress: + def __init__(self, described = 0, total = 0): + self.described = described + self.total = total + + def __add__(self, other): + return ClassStatusProgress(self.described + other.described, self.total + other.total) + + def increment(self, described): + if described: + self.described += 1 + self.total += 1 + + def is_ok(self): + return self.described >= self.total + + def to_configured_colored_string(self): + if flags['p']: + return self.to_colored_string('{percent}% ({has}/{total})', '{pad_percent}{pad_described}{s}{pad_total}') + else: + return self.to_colored_string() + + def to_colored_string(self, format='{has}/{total}', pad_format='{pad_described}{s}{pad_total}'): + ratio = self.described/self.total if self.total != 0 else 1 + percent = round(100*ratio) + s = format.format(has = str(self.described), total = str(self.total), percent = str(percent)) + if self.described >= self.total: + s = color('part_good', s) + elif self.described >= self.total/4*3: + s = color('part_mostly_good', s) + elif self.described > 0: + s = color('part_problem', s) + else: + s = color('part_big_problem', s) + pad_size = max(len(str(self.described)), len(str(self.total))) + pad_described = ''.ljust(pad_size - len(str(self.described))) + pad_percent = ''.ljust(3 - len(str(percent))) + pad_total = ''.ljust(pad_size - len(str(self.total))) + return pad_format.format(pad_described = pad_described, pad_total = pad_total, pad_percent = pad_percent, s = s) + + +class ClassStatus: + def __init__(self, name=''): + self.name = name + self.has_brief_description = True + self.has_description = True + self.progresses = { + 'methods': ClassStatusProgress(), + 'constants': ClassStatusProgress(), + 'members': ClassStatusProgress(), + 'signals': ClassStatusProgress() + } + + def __add__(self, other): + new_status = ClassStatus() + new_status.name = self.name + new_status.has_brief_description = self.has_brief_description and other.has_brief_description + new_status.has_description = self.has_description and other.has_description + for k in self.progresses: + new_status.progresses[k] = self.progresses[k] + other.progresses[k] + return new_status + + def is_ok(self): + ok = True + ok = ok and self.has_brief_description + ok = ok and self.has_description + for k in self.progresses: + ok = ok and self.progresses[k].is_ok() + return ok + + def make_output(self): + output = {} + output['name'] = color('name', self.name) + + ok_string = color('part_good', 'OK') + missing_string = color('part_big_problem', 'MISSING') + + output['brief_description'] = ok_string if self.has_brief_description else missing_string + output['description'] = ok_string if self.has_description else missing_string + + description_progress = ClassStatusProgress( + (self.has_brief_description + self.has_description) * overall_progress_description_weigth, + 2 * overall_progress_description_weigth + ) + items_progress = ClassStatusProgress() + + for k in ['methods', 'constants', 'members', 'signals']: + items_progress += self.progresses[k] + output[k] = self.progresses[k].to_configured_colored_string() + + output['items'] = items_progress.to_configured_colored_string() + + output['overall'] = (description_progress + items_progress).to_colored_string('{percent}%', '{pad_percent}{s}') + + if self.name.startswith('Total'): + output['url'] = color('url', 'http://docs.godotengine.org/en/latest/classes/_classes.html') + output['comment'] = color('part_good', 'ALL OK') + else: + output['url'] = color('url', 'http://docs.godotengine.org/en/latest/classes/class_{name}.html'.format(name=self.name.lower())) + + if not flags['g'] and self.is_ok(): + output['comment'] = color('part_good', 'ALL OK') + + return output + + def generate_for_class(c): + status = ClassStatus() + status.name = c.attrib['name'] + for tag in list(c): + + if tag.tag == 'brief_description': + status.has_brief_description = len(tag.text.strip()) > 0 + + elif tag.tag == 'description': + status.has_description = len(tag.text.strip()) > 0 + + elif tag.tag in ['methods', 'signals']: + for sub_tag in list(tag): + descr = sub_tag.find('description') + status.progresses[tag.tag].increment(len(descr.text.strip()) > 0) + + elif tag.tag in ['constants', 'members']: + for sub_tag in list(tag): + status.progresses[tag.tag].increment(len(sub_tag.text.strip()) > 0) + + elif tag.tag in ['theme_items']: + pass #Ignore those tags, since they seem to lack description at all + + else: + print(tag.tag, tag.attrib) + + return status + + + +################################################################################ +# Arguments # +################################################################################ + +input_file_list = [] +input_class_list = [] + +for arg in sys.argv[1:]: + if arg.startswith('--'): + flags[long_flags[arg[2:]]] = not flags[long_flags[arg[2:]]] + elif arg.startswith('-'): + for f in arg[1:]: + flags[f] = not flags[f] + elif arg.endswith('.xml'): + input_file_list.append(arg) + else: + input_class_list.append(arg) + +if flags['i']: + for r in ['methods', 'constants', 'members', 'signals']: + index = table_columns.index(r) + del table_column_names[index] + del table_columns[index] + table_column_names.append('Items') + table_columns.append('items') + +if flags['o'] == (not flags['i']): + table_column_names.append('Overall') + table_columns.append('overall') + +if flags['u']: + table_column_names.append('Docs URL') + table_columns.append('url') + + +################################################################################ +# Help # +################################################################################ + +if len(input_file_list) < 1 or flags['h']: + if not flags['h']: + print(color('section', 'Invalid usage') + ': At least one classes.xml file is required') + print(color('section', 'Usage') + ': doc_status.py [flags] <classes.xml> [class names]') + print('\t< and > signify required parameters, while [ and ] signify optional parameters.') + print('\tNote that you can give more than one classes file, in which case they will be merged on-the-fly.') + print(color('section', 'Available flags') + ':') + possible_synonym_list = list(long_flags) + possible_synonym_list.sort() + flag_list = list(flags) + flag_list.sort() + for flag in flag_list: + synonyms = [color('name', '-' + flag)] + for synonym in possible_synonym_list: + if long_flags[synonym] == flag: + synonyms.append(color('name', '--' + synonym)) + + print(('{synonyms} (Currently '+color('state_'+('on' if flags[flag] else 'off'), '{value}')+')\n\t{description}').format( + synonyms = ', '.join(synonyms), + value = ('on' if flags[flag] else 'off'), + description = flag_descriptions[flag] + )) + sys.exit(0) + + + +################################################################################ +# Parse class list # +################################################################################ + +class_names = [] +classes = {} + +for file in input_file_list: + tree = ET.parse(file) + doc = tree.getroot() + + if 'version' not in doc.attrib: + print('Version missing from "doc"') + sys.exit(255) + + version = doc.attrib['version'] + + for c in list(doc): + if c.attrib['name'] in class_names: + continue + class_names.append(c.attrib['name']) + classes[c.attrib['name']] = c + +class_names.sort() + +if len(input_class_list) < 1: + input_class_list = class_names + + + +################################################################################ +# Make output table # +################################################################################ + +table = [table_column_names] +table_row_chars = '+- ' +table_column_chars = '|' + +total_status = ClassStatus('Total') + +for cn in input_class_list: + if not cn in classes: + print('Cannot find class ' + cn + '!') + sys.exit(255) + + c = classes[cn] + validate_tag(c, 'class') + status = ClassStatus.generate_for_class(c) + + if flags['b'] and status.is_ok(): + continue + if flags['g'] and not status.is_ok(): + continue + + total_status = total_status + status + out = status.make_output() + row = [] + for column in table_columns: + if column in out: + row.append(out[column]) + else: + row.append('') + + if 'comment' in out and out['comment'] != '': + row.append(out['comment']) + + table.append(row) + + + + +################################################################################ +# Print output table # +################################################################################ + +if len(table) == 1: + print(color('part_big_problem', 'No classes suitable for printing!')) + sys.exit(0) + +if len(table) > 2: + total_status.name = 'Total = {0}'.format(len(table) - 1) + out = total_status.make_output() + row = [] + for column in table_columns: + if column in out: + row.append(out[column]) + else: + row.append('') + table.append(row) + +table_column_sizes = [] +for row in table: + for cell_i, cell in enumerate(row): + if cell_i >= len(table_column_sizes): + table_column_sizes.append(0) + + table_column_sizes[cell_i] = max(nonescape_len(cell), table_column_sizes[cell_i]) + +divider_string = table_row_chars[0] +for cell_i in range(len(table[0])): + divider_string += table_row_chars[1] * (table_column_sizes[cell_i] + 2) + table_row_chars[0] +print(divider_string) + +for row_i, row in enumerate(table): + row_string = table_column_chars + for cell_i, cell in enumerate(row): + padding_needed = table_column_sizes[cell_i] - nonescape_len(cell) + 2 + if cell_i == 0: + row_string += table_row_chars[2] + cell + table_row_chars[2]*(padding_needed-1) + else: + row_string += table_row_chars[2]*math.floor(padding_needed/2) + cell + table_row_chars[2]*math.ceil((padding_needed/2)) + row_string += table_column_chars + + print(row_string) + + if row_i == 0 or row_i == len(table) - 2: + print(divider_string) + +print(divider_string) + +if total_status.is_ok() and not flags['g']: + print('All listed classes are ' + color('part_good', 'OK') + '!') + |