23e08b0fad
- Duplicate the header when the `-a` flag is enabled. Since lots of
items are displayed in this case, this helps the user remember
which column is which without having to scroll back to the top.
- Bolden the overall percentages for easier visual grepping.
(cherry picked from commit 7c3f6b2870)
479 lines
16 KiB
Python
Executable File
479 lines
16 KiB
Python
Executable File
#!/usr/bin/env python
|
|
|
|
import fnmatch
|
|
import os
|
|
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,
|
|
's': False,
|
|
'u': False,
|
|
'h': False,
|
|
'p': False,
|
|
'o': True,
|
|
'i': False,
|
|
'a': True,
|
|
'e': False,
|
|
}
|
|
flag_descriptions = {
|
|
'c': 'Toggle colors when outputting.',
|
|
'b': 'Toggle showing only not fully described classes.',
|
|
'g': 'Toggle showing only completed classes.',
|
|
's': 'Toggle showing comments about the status.',
|
|
'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.',
|
|
'a': 'Toggle showing all items.',
|
|
'e': 'Toggle hiding empty items.',
|
|
}
|
|
long_flags = {
|
|
'colors': 'c',
|
|
'use-colors': 'c',
|
|
|
|
'bad': 'b',
|
|
'only-bad': 'b',
|
|
|
|
'good': 'g',
|
|
'only-good': 'g',
|
|
|
|
'comments': 's',
|
|
'status': 's',
|
|
|
|
'urls': 'u',
|
|
'gen-url': 'u',
|
|
|
|
'help': 'h',
|
|
|
|
'percent': 'p',
|
|
'use-percentages': 'p',
|
|
|
|
'overall': 'o',
|
|
'use-overall': 'o',
|
|
|
|
'items': 'i',
|
|
'collapse': 'i',
|
|
|
|
'all': 'a',
|
|
|
|
'empty': 'e',
|
|
}
|
|
table_columns = ['name', 'brief_description', 'description', 'methods', 'constants', 'members', 'signals', 'theme_items']
|
|
table_column_names = ['Name', 'Brief Desc.', 'Desc.', 'Methods', 'Constants', 'Members', 'Signals', 'Theme Items']
|
|
colors = {
|
|
'name': [36], # cyan
|
|
'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
|
|
'bold': [1], # bold
|
|
}
|
|
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'] and terminal_supports_color():
|
|
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))
|
|
|
|
def terminal_supports_color():
|
|
p = sys.platform
|
|
supported_platform = p != 'Pocket PC' and (p != 'win32' or
|
|
'ANSICON' in os.environ)
|
|
|
|
is_a_tty = hasattr(sys.stdout, 'isatty') and sys.stdout.isatty()
|
|
if not supported_platform or not is_a_tty:
|
|
return False
|
|
return True
|
|
|
|
################################################################################
|
|
# 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 = float(self.described) / float(self.total) if self.total != 0 else 1
|
|
percent = int(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(),
|
|
'theme_items': 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 is_empty(self):
|
|
sum = 0
|
|
for k in self.progresses:
|
|
if self.progresses[k].is_ok():
|
|
continue
|
|
sum += self.progresses[k].total
|
|
return sum < 1
|
|
|
|
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', 'theme_items']:
|
|
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(color('bold', '{percent}%'), '{pad_percent}{s}')
|
|
|
|
if self.name.startswith('Total'):
|
|
output['url'] = color('url', 'https://docs.godotengine.org/en/latest/classes/')
|
|
if flags['s']:
|
|
output['comment'] = color('part_good', 'ALL OK')
|
|
else:
|
|
output['url'] = color('url', 'https://docs.godotengine.org/en/latest/classes/class_{name}.html'.format(name=self.name.lower()))
|
|
|
|
if flags['s'] and not flags['g'] and self.is_ok():
|
|
output['comment'] = color('part_good', 'ALL OK')
|
|
|
|
return output
|
|
|
|
@staticmethod
|
|
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', 'theme_items']:
|
|
for sub_tag in list(tag):
|
|
if not sub_tag.text is None:
|
|
status.progresses[tag.tag].increment(len(sub_tag.text.strip()) > 0)
|
|
|
|
elif tag.tag in ['tutorials']:
|
|
pass # Ignore those tags for now
|
|
|
|
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 = []
|
|
merged_file = ""
|
|
|
|
for arg in sys.argv[1:]:
|
|
try:
|
|
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 os.path.isdir(arg):
|
|
for f in os.listdir(arg):
|
|
if f.endswith('.xml'):
|
|
input_file_list.append(os.path.join(arg, f));
|
|
else:
|
|
input_class_list.append(arg)
|
|
except KeyError:
|
|
print("Unknown command line flag: " + arg)
|
|
sys.exit(1)
|
|
|
|
if flags['i']:
|
|
for r in ['methods', 'constants', 'members', 'signals', 'theme_items']:
|
|
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(color('bold', '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') + ': Please specify a classes directory')
|
|
print(color('section', 'Usage') + ': doc_status.py [flags] <classes_dir> [class names]')
|
|
print('\t< and > signify required parameters, while [ and ] signify optional parameters.')
|
|
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']
|
|
|
|
if doc.attrib['name'] in class_names:
|
|
continue
|
|
class_names.append(doc.attrib['name'])
|
|
classes[doc.attrib['name']] = doc
|
|
|
|
class_names.sort()
|
|
|
|
if len(input_class_list) < 1:
|
|
input_class_list = ['*']
|
|
|
|
filtered_classes = set()
|
|
for pattern in input_class_list:
|
|
filtered_classes |= set(fnmatch.filter(class_names, pattern))
|
|
filtered_classes = list(filtered_classes)
|
|
filtered_classes.sort()
|
|
|
|
################################################################################
|
|
# Make output table #
|
|
################################################################################
|
|
|
|
table = [table_column_names]
|
|
table_row_chars = '| - '
|
|
table_column_chars = '|'
|
|
|
|
total_status = ClassStatus('Total')
|
|
|
|
for cn in filtered_classes:
|
|
|
|
c = classes[cn]
|
|
validate_tag(c, 'class')
|
|
status = ClassStatus.generate_for_class(c)
|
|
|
|
total_status = total_status + status
|
|
|
|
if (flags['b'] and status.is_ok()) or (flags['g'] and not status.is_ok()) or (not flags['a']):
|
|
continue
|
|
|
|
if flags['e'] and status.is_empty():
|
|
continue
|
|
|
|
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 and flags['a']:
|
|
print(color('part_big_problem', 'No classes suitable for printing!'))
|
|
sys.exit(0)
|
|
|
|
if len(table) > 2 or not flags['a']:
|
|
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)
|
|
|
|
if flags['a']:
|
|
# Duplicate the headers at the bottom of the table so they can be viewed
|
|
# without having to scroll back to the top.
|
|
table.append(table_column_names)
|
|
|
|
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_row_chars[2] * (table_column_sizes[cell_i]) + table_row_chars[1] + 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[3] + cell + table_row_chars[3] * (padding_needed - 1)
|
|
else:
|
|
row_string += table_row_chars[3] * int(math.floor(float(padding_needed) / 2)) + cell + table_row_chars[3] * int(math.ceil(float(padding_needed) / 2))
|
|
row_string += table_column_chars
|
|
|
|
print(row_string)
|
|
|
|
# Account for the possible double header (if the `a` flag is enabled).
|
|
# No need to have a condition for the flag, as this will behave correctly
|
|
# if the flag is disabled.
|
|
if row_i == 0 or row_i == len(table) - 3 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') + '!')
|