diff options
Diffstat (limited to 'doc/tools')
| -rw-r--r-- | doc/tools/doc_merge.py | 2 | ||||
| -rw-r--r-- | doc/tools/doc_status.py | 4 | ||||
| -rw-r--r-- | doc/tools/makemd.py | 360 | ||||
| -rwxr-xr-x | doc/tools/makerst.py | 1073 |
4 files changed, 689 insertions, 750 deletions
diff --git a/doc/tools/doc_merge.py b/doc/tools/doc_merge.py index 57ac4bdcdd..496d5dcb74 100644 --- a/doc/tools/doc_merge.py +++ b/doc/tools/doc_merge.py @@ -82,7 +82,7 @@ def find_signal_descr(old_class, name): def find_constant_descr(old_class, name): - if (old_class == None): + if (old_class is None): return None constants = old_class.find("constants") if(constants != None and len(list(constants)) > 0): diff --git a/doc/tools/doc_status.py b/doc/tools/doc_status.py index ab74c0b9d6..4bb4342d5f 100644 --- a/doc/tools/doc_status.py +++ b/doc/tools/doc_status.py @@ -229,11 +229,11 @@ class ClassStatus: 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/') + 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', 'http://docs.godotengine.org/en/latest/classes/class_{name}.html'.format(name=self.name.lower())) + 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') diff --git a/doc/tools/makemd.py b/doc/tools/makemd.py deleted file mode 100644 index 056f1ca82d..0000000000 --- a/doc/tools/makemd.py +++ /dev/null @@ -1,360 +0,0 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- - -import sys -import os.path as path -import os -import xml.etree.ElementTree as ET - -input_list = [] - -for arg in sys.argv[1:]: - if not path.exists(arg): - exit("path {} doesn't exist".format(arg)) - elif path.isdir(arg): - input_list += filter(path.isfile, [path.join(arg, f) for f in os.listdir(arg)]) - else: # assuming is a file - input_list.append(arg) - -if len(input_list) < 1: - print 'usage: makemd.py <classes.xml>' - sys.exit(0) - - -def validate_tag(elem, tag): - if elem.tag != tag: - print "Tag mismatch, expected '" + tag + "', got " + elem.tag - sys.exit(255) - - -class_names = [] -classes = {} - - -def make_class_list(class_list, columns): - - f = open('class_list.md', 'wb') - prev = 0 - col_max = len(class_list) / columns + 1 - col_count = 0 - row_count = 0 - last_initial = '' - fit_columns = [] - - for n in range(0, columns): - fit_columns += [[]] - - indexers = [] - last_initial = '' - - idx = 0 - for n in class_list: - col = idx / col_max - if col >= columns: - col = columns - 1 - fit_columns[col] += [n] - idx += 1 - if n[:1] != last_initial: - indexers += [n] - last_initial = n[:1] - - row_max = 0 - f.write("\n") - - for n in range(0, columns): - if len(fit_columns[n]) > row_max: - row_max = len(fit_columns[n]) - - f.write("| ") - for n in range(0, columns): - f.write(" | |") - - f.write("\n") - f.write("| ") - for n in range(0, columns): - f.write(" --- | ------- |") - f.write("\n") - - for r in range(0, row_max): - s = '| ' - for c in range(0, columns): - if r >= len(fit_columns[c]): - continue - - classname = fit_columns[c][r] - initial = classname[0] - if classname in indexers: - s += '**' + initial + '** | ' - else: - s += ' | ' - - s += '[' + classname + '](class_' + classname.lower() + ') | ' - - s += '\n' - f.write(s) - - f.close() - - -def dokuize_text(txt): - - return txt - - -def dokuize_text(text): - pos = 0 - while True: - pos = text.find('[', pos) - if pos == -1: - break - - endq_pos = text.find(']', pos + 1) - if endq_pos == -1: - break - - pre_text = text[:pos] - post_text = text[endq_pos + 1:] - tag_text = text[pos + 1:endq_pos] - - if tag_text in class_names: - tag_text = make_type(tag_text) - else: - - # command - - cmd = tag_text - space_pos = tag_text.find(' ') - if cmd.find('html') == 0: - cmd = tag_text[:space_pos] - param = tag_text[space_pos + 1:] - tag_text = '<' + param + '>' - elif cmd.find('method') == 0: - cmd = tag_text[:space_pos] - param = tag_text[space_pos + 1:] - - if param.find('.') != -1: - (class_param, method_param) = param.split('.') - tag_text = '[' + class_param + '.' + method_param.replace("_", "_") + '](' + class_param.lower() + '#' \ - + method_param + ')' - else: - tag_text = '[' + param.replace("_", "_") + '](#' + param + ')' - elif cmd.find('image=') == 0: - tag_text = '' - elif cmd.find('url=') == 0: - tag_text = '[' + cmd[4:] + '](' + cmd[4:] - elif cmd == '/url': - tag_text = ')' - elif cmd == 'center': - tag_text = '' - elif cmd == '/center': - tag_text = '' - elif cmd == 'br': - tag_text = '\n' - elif cmd == 'i' or cmd == '/i': - tag_text = '_' - elif cmd == 'b' or cmd == '/b': - tag_text = '**' - elif cmd == 'u' or cmd == '/u': - tag_text = '__' - else: - tag_text = '[' + tag_text + ']' - - text = pre_text + tag_text + post_text - pos = len(pre_text) + len(tag_text) - - # tnode = ET.SubElement(parent,"div") - # tnode.text=text - - return text - - -def make_type(t): - global class_names - if t in class_names: - return '[' + t + '](class_' + t.lower() + ')' - return t - - -def make_method( - f, - name, - m, - declare, - event=False, -): - - s = ' * ' - ret_type = 'void' - args = list(m) - mdata = {} - mdata['argidx'] = [] - for a in args: - if a.tag == 'return': - idx = -1 - elif a.tag == 'argument': - idx = int(a.attrib['index']) - else: - continue - - mdata['argidx'].append(idx) - mdata[idx] = a - - if not event: - if -1 in mdata['argidx']: - s += make_type(mdata[-1].attrib['type']) - else: - s += 'void' - s += ' ' - - if declare: - - # span.attrib["class"]="funcdecl" - # a=ET.SubElement(span,"a") - # a.attrib["name"]=name+"_"+m.attrib["name"] - # a.text=name+"::"+m.attrib["name"] - - s += ' **' + m.attrib['name'].replace("_", "_") + '** ' - else: - s += ' **[' + m.attrib['name'].replace("_", "_") + '](#' + m.attrib['name'] + ')** ' - - s += ' **(**' - argfound = False - for a in mdata['argidx']: - arg = mdata[a] - if a < 0: - continue - if a > 0: - s += ', ' - else: - s += ' ' - - s += make_type(arg.attrib['type']) - if 'name' in arg.attrib: - s += ' ' + arg.attrib['name'] - else: - s += ' arg' + str(a) - - if 'default' in arg.attrib: - s += '=' + arg.attrib['default'] - - argfound = True - - if argfound: - s += ' ' - s += ' **)**' - - if 'qualifiers' in m.attrib: - s += ' ' + m.attrib['qualifiers'] - - f.write(s + '\n') - - -def make_doku_class(node): - - name = node.attrib['name'] - - f = open("class_" + name.lower() + '.md', 'wb') - - f.write('# ' + name + ' \n') - - if 'inherits' in node.attrib: - inh = node.attrib['inherits'].strip() - f.write('####**Inherits:** ' + make_type(inh) + '\n') - if 'category' in node.attrib: - f.write('####**Category:** ' + node.attrib['category'].strip() - + '\n') - - briefd = node.find('brief_description') - if briefd != None: - f.write('\n### Brief Description \n') - f.write(dokuize_text(briefd.text.strip()) + '\n') - - methods = node.find('methods') - - if methods != None and len(list(methods)) > 0: - f.write('\n### Member Functions \n') - for m in list(methods): - make_method(f, node.attrib['name'], m, False) - - events = node.find('signals') - if events != None and len(list(events)) > 0: - f.write('\n### Signals \n') - for m in list(events): - make_method(f, node.attrib['name'], m, True, True) - d = m.find('description') - if d == None or d.text.strip() == '': - continue - f.write('\n') - f.write(dokuize_text(d.text.strip())) - f.write('\n') - - members = node.find('members') - - if members != None and len(list(members)) > 0: - f.write('\n### Member Variables \n') - - for c in list(members): - s = ' * ' - s += make_type(c.attrib['type']) + ' ' - s += '**' + c.attrib['name'] + '**' - if c.text.strip() != '': - s += ' - ' + c.text.strip() - f.write(s + '\n') - - constants = node.find('constants') - if constants != None and len(list(constants)) > 0: - f.write('\n### Numeric Constants \n') - for c in list(constants): - s = ' * ' - s += '**' + c.attrib['name'] + '**' - if 'value' in c.attrib: - s += ' = **' + c.attrib['value'] + '**' - if c.text.strip() != '': - s += ' - ' + c.text.strip() - f.write(s + '\n') - - descr = node.find('description') - if descr != None and descr.text.strip() != '': - f.write('\n### Description \n') - f.write(dokuize_text(descr.text.strip()) + '\n') - - methods = node.find('methods') - - if methods != None and len(list(methods)) > 0: - f.write('\n### Member Function Description \n') - for m in list(methods): - - d = m.find('description') - if d == None or d.text.strip() == '': - continue - f.write('\n#### <a name="' + m.attrib['name'] + '">' + m.attrib['name'] + '</a>\n') - make_method(f, node.attrib['name'], m, True) - f.write('\n') - f.write(dokuize_text(d.text.strip())) - f.write('\n') - - f.close() - - -for file in input_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'] - class_name = doc.attrib['name'] - if class_name in class_names: - continue - class_names.append(class_name) - classes[class_name] = doc - -class_names.sort() - -make_class_list(class_names, 2) - -for cn in class_names: - c = classes[cn] - make_doku_class(c) diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py index 93ad823d42..4b5785f604 100755 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -1,73 +1,563 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- +#!/usr/bin/env python3 -import codecs +import argparse import sys import os import re import xml.etree.ElementTree as ET +from collections import defaultdict, OrderedDict -input_list = [] -cur_file = "" +# Uncomment to do type checks. I have it commented out so it works below Python 3.5 +#from typing import List, Dict, TextIO, Tuple, Iterable, Optional, DefaultDict, Any, Union # http(s)://docs.godotengine.org/<langcode>/<tag>/path/to/page.html(#fragment-tag) -godot_docs_pattern = re.compile('^http(?:s)?:\/\/docs\.godotengine\.org\/(?:[a-zA-Z0-9\.\-_]*)\/(?:[a-zA-Z0-9\.\-_]*)\/(.*)\.html(#.*)?$') +GODOT_DOCS_PATTERN = re.compile(r'^http(?:s)?://docs\.godotengine\.org/(?:[a-zA-Z0-9.\-_]*)/(?:[a-zA-Z0-9.\-_]*)/(.*)\.html(#.*)?$') -for arg in sys.argv[1:]: - if arg.endswith(os.sep): - arg = arg[:-1] - input_list.append(arg) -if len(input_list) < 1: - print('usage: makerst.py <path to folders> and/or <path to .xml files> (order of arguments irrelevant)') - print('example: makerst.py "../../modules/" "../classes" path_to/some_class.xml') - sys.exit(0) +def print_error(error, state): # type: (str, State) -> None + print(error) + state.errored = True -def validate_tag(elem, tag): - if elem.tag != tag: - print("Tag mismatch, expected '" + tag + "', got " + elem.tag) - sys.exit(255) +class TypeName: + def __init__(self, type_name, enum=None): # type: (str, Optional[str]) -> None + self.type_name = type_name + self.enum = enum + def to_rst(self, state): # type: ("State") -> str + if self.enum is not None: + return make_enum(self.enum, state) + elif self.type_name == "void": + return "void" + else: + return make_type(self.type_name, state) + + @classmethod + def from_element(cls, element): # type: (ET.Element) -> "TypeName" + return cls(element.attrib["type"], element.get("enum")) + + +class PropertyDef: + def __init__(self, name, type_name, setter, getter, text): # type: (str, TypeName, Optional[str], Optional[str], Optional[str]) -> None + self.name = name + self.type_name = type_name + self.setter = setter + self.getter = getter + self.text = text + +class ParameterDef: + def __init__(self, name, type_name, default_value): # type: (str, TypeName, Optional[str]) -> None + self.name = name + self.type_name = type_name + self.default_value = default_value + + +class SignalDef: + def __init__(self, name, parameters, description): # type: (str, List[ParameterDef], Optional[str]) -> None + self.name = name + self.parameters = parameters + self.description = description + + +class MethodDef: + def __init__(self, name, return_type, parameters, description, qualifiers): # type: (str, TypeName, List[ParameterDef], Optional[str], Optional[str]) -> None + self.name = name + self.return_type = return_type + self.parameters = parameters + self.description = description + self.qualifiers = qualifiers + + +class ConstantDef: + def __init__(self, name, value, text): # type: (str, str, Optional[str]) -> None + self.name = name + self.value = value + self.text = text + + +class EnumDef: + def __init__(self, name): # type: (str) -> None + self.name = name + self.values = OrderedDict() # type: OrderedDict[str, ConstantDef] + + +class ThemeItemDef: + def __init__(self, name, type_name): # type: (str, TypeName) -> None + self.name = name + self.type_name = type_name + + +class ClassDef: + def __init__(self, name): # type: (str) -> None + self.name = name + self.constants = OrderedDict() # type: OrderedDict[str, ConstantDef] + self.enums = OrderedDict() # type: OrderedDict[str, EnumDef] + self.properties = OrderedDict() # type: OrderedDict[str, PropertyDef] + self.methods = OrderedDict() # type: OrderedDict[str, List[MethodDef]] + self.signals = OrderedDict() # type: OrderedDict[str, SignalDef] + self.inherits = None # type: Optional[str] + self.category = None # type: Optional[str] + self.brief_description = None # type: Optional[str] + self.description = None # type: Optional[str] + self.theme_items = None # type: Optional[OrderedDict[str, List[ThemeItemDef]]] + self.tutorials = [] # type: List[str] + + +class State: + def __init__(self): # type: () -> None + # Has any error been reported? + self.errored = False + self.classes = OrderedDict() # type: OrderedDict[str, ClassDef] + self.current_class = "" # type: str + + def parse_class(self, class_root): # type: (ET.Element) -> None + class_name = class_root.attrib["name"] + + class_def = ClassDef(class_name) + self.classes[class_name] = class_def + + inherits = class_root.get("inherits") + if inherits is not None: + class_def.inherits = inherits + + category = class_root.get("category") + if category is not None: + class_def.category = category + + brief_desc = class_root.find("brief_description") + if brief_desc is not None and brief_desc.text: + class_def.brief_description = brief_desc.text + + desc = class_root.find("description") + if desc is not None and desc.text: + class_def.description = desc.text + + properties = class_root.find("members") + if properties is not None: + for property in properties: + assert property.tag == "member" + + property_name = property.attrib["name"] + if property_name in class_def.properties: + print_error("Duplicate property '{}', file: {}".format(property_name, class_name), self) + continue + + type_name = TypeName.from_element(property) + setter = property.get("setter") or None # Use or None so '' gets turned into None. + getter = property.get("getter") or None + + property_def = PropertyDef(property_name, type_name, setter, getter, property.text) + class_def.properties[property_name] = property_def + + methods = class_root.find("methods") + if methods is not None: + for method in methods: + assert method.tag == "method" + + method_name = method.attrib["name"] + qualifiers = method.get("qualifiers") + + return_element = method.find("return") + if return_element is not None: + return_type = TypeName.from_element(return_element) + + else: + return_type = TypeName("void") + + params = parse_arguments(method) + + desc_element = method.find("description") + method_desc = None + if desc_element is not None: + method_desc = desc_element.text + + method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers) + if method_name not in class_def.methods: + class_def.methods[method_name] = [] + + class_def.methods[method_name].append(method_def) + + constants = class_root.find("constants") + if constants is not None: + for constant in constants: + assert constant.tag == "constant" + + constant_name = constant.attrib["name"] + value = constant.attrib["value"] + enum = constant.get("enum") + constant_def = ConstantDef(constant_name, value, constant.text) + if enum is None: + if constant_name in class_def.constants: + print_error("Duplicate constant '{}', file: {}".format(constant_name, class_name), self) + continue + + class_def.constants[constant_name] = constant_def + + else: + if enum in class_def.enums: + enum_def = class_def.enums[enum] + + else: + enum_def = EnumDef(enum) + class_def.enums[enum] = enum_def + + enum_def.values[constant_name] = constant_def + + signals = class_root.find("signals") + if signals is not None: + for signal in signals: + assert signal.tag == "signal" + + signal_name = signal.attrib["name"] + + if signal_name in class_def.signals: + print_error("Duplicate signal '{}', file: {}".format(signal_name, class_name), self) + continue -class_names = [] -classes = {} + params = parse_arguments(signal) + desc_element = signal.find("description") + signal_desc = None + if desc_element is not None: + signal_desc = desc_element.text -def ul_string(str, ul): - str += "\n" - for i in range(len(str) - 1): - str += ul - str += "\n" - return str + signal_def = SignalDef(signal_name, params, signal_desc) + class_def.signals[signal_name] = signal_def + theme_items = class_root.find("theme_items") + if theme_items is not None: + class_def.theme_items = OrderedDict() + for theme_item in theme_items: + assert theme_item.tag == "theme_item" + + theme_item_name = theme_item.attrib["name"] + theme_item_def = ThemeItemDef(theme_item_name, TypeName.from_element(theme_item)) + if theme_item_name not in class_def.theme_items: + class_def.theme_items[theme_item_name] = [] + class_def.theme_items[theme_item_name].append(theme_item_def) + + tutorials = class_root.find("tutorials") + if tutorials is not None: + for link in tutorials: + assert link.tag == "link" + + if link.text is not None: + class_def.tutorials.append(link.text) + + + + def sort_classes(self): # type: () -> None + self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0])) + + +def parse_arguments(root): # type: (ET.Element) -> List[ParameterDef] + param_elements = root.findall("argument") + params = [None] * len(param_elements) # type: Any + for param_element in param_elements: + param_name = param_element.attrib["name"] + index = int(param_element.attrib["index"]) + type_name = TypeName.from_element(param_element) + default = param_element.get("default") + + params[index] = ParameterDef(param_name, type_name, default) + + cast = params # type: List[ParameterDef] + + return cast + + +def main(): # type: () -> None + parser = argparse.ArgumentParser() + parser.add_argument("path", nargs="+", help="A path to an XML file or a directory containing XML files to parse.") + group = parser.add_mutually_exclusive_group() + group.add_argument("--output", "-o", default=".", help="The directory to save output .rst files in.") + group.add_argument("--dry-run", action="store_true", help="If passed, no output will be generated and XML files are only checked for errors.") + args = parser.parse_args() + + file_list = [] # type: List[str] + + for path in args.path: + # Cut off trailing slashes so os.path.basename doesn't choke. + if path.endswith(os.sep): + path = path[:-1] + + if os.path.basename(path) == 'modules': + for subdir, dirs, _ in os.walk(path): + if 'doc_classes' in dirs: + doc_dir = os.path.join(subdir, 'doc_classes') + class_file_names = (f for f in os.listdir(doc_dir) if f.endswith('.xml')) + file_list += (os.path.join(doc_dir, f) for f in class_file_names) + + elif os.path.isdir(path): + file_list += (os.path.join(path, f) for f in os.listdir(path) if f.endswith('.xml')) + + elif os.path.isfile(path): + if not path.endswith(".xml"): + print("Got non-.xml file '{}' in input, skipping.".format(path)) + continue + + file_list.append(path) + + classes = {} # type: Dict[str, ET.Element] + state = State() + + for cur_file in file_list: + try: + tree = ET.parse(cur_file) + except ET.ParseError as e: + print_error("Parse error reading file '{}': {}".format(cur_file, e), state) + continue + doc = tree.getroot() + + if 'version' not in doc.attrib: + print_error("Version missing from 'doc', file: {}".format(cur_file), state) + continue -def make_class_list(class_list, columns): - f = codecs.open('class_list.rst', 'wb', 'utf-8') - prev = 0 - col_max = len(class_list) / columns + 1 + name = doc.attrib["name"] + if name in classes: + print_error("Duplicate class '{}'".format(name), state) + continue + + classes[name] = doc + + for name, data in classes.items(): + try: + state.parse_class(data) + except Exception as e: + print_error("Exception while parsing class '{}': {}".format(name, e), state) + + state.sort_classes() + + for class_name, class_def in state.classes.items(): + state.current_class = class_name + make_rst_class(class_def, state, args.dry_run, args.output) + + if state.errored: + exit(1) + +def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, State, bool, str) -> None + class_name = class_def.name + + if dry_run: + f = open(os.devnull, "w") + else: + f = open(os.path.join(output_dir, "class_" + class_name.lower() + '.rst'), 'w', encoding='utf-8') + + # Warn contributors not to edit this file directly + f.write(".. Generated automatically by doc/tools/makerst.py in Godot's source tree.\n") + f.write(".. DO NOT EDIT THIS FILE, but the " + class_name + ".xml source instead.\n") + f.write(".. The source is found in doc/classes or modules/<name>/doc_classes.\n\n") + + f.write(".. _class_" + class_name + ":\n\n") + f.write(make_heading(class_name, '=')) + + # Inheritance tree + # Ascendants + if class_def.inherits: + inh = class_def.inherits.strip() + f.write('**Inherits:** ') + first = True + while inh in state.classes: + if not first: + f.write(" **<** ") + else: + first = False + + f.write(make_type(inh, state)) + inode = state.classes[inh].inherits + if inode: + inh = inode.strip() + else: + break + f.write("\n\n") + + # Descendents + inherited = [] + for c in state.classes.values(): + if c.inherits and c.inherits.strip() == class_name: + inherited.append(c.name) + + if len(inherited): + f.write('**Inherited By:** ') + for i, child in enumerate(inherited): + if i > 0: + f.write(", ") + f.write(make_type(child, state)) + f.write("\n\n") + + # Category + if class_def.category is not None: + f.write('**Category:** ' + class_def.category.strip() + "\n\n") + + # Brief description + f.write(make_heading('Brief Description', '-')) + if class_def.brief_description is not None: + f.write(rstize_text(class_def.brief_description.strip(), state) + "\n\n") + + # Properties overview + if len(class_def.properties) > 0: + f.write(make_heading('Properties', '-')) + ml = [] # type: List[Tuple[str, str]] + for property_def in class_def.properties.values(): + type_rst = property_def.type_name.to_rst(state) + ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name) + ml.append((type_rst, ref)) + format_table(f, ml) + + # Methods overview + if len(class_def.methods) > 0: + f.write(make_heading('Methods', '-')) + ml = [] + for method_list in class_def.methods.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, True, state)) + format_table(f, ml) + + # Theme properties + if class_def.theme_items is not None and len(class_def.theme_items) > 0: + f.write(make_heading('Theme Properties', '-')) + ml = [] + for theme_item_list in class_def.theme_items.values(): + for theme_item in theme_item_list: + ml.append((theme_item.type_name.to_rst(state), theme_item.name)) + format_table(f, ml) + + # Signals + if len(class_def.signals) > 0: + f.write(make_heading('Signals', '-')) + for signal in class_def.signals.values(): + #f.write(".. _class_{}_{}:\n\n".format(class_name, signal.name)) + f.write(".. _class_{}_signal_{}:\n\n".format(class_name, signal.name)) + _, signature = make_method_signature(class_def, signal, False, state) + f.write("- {}\n\n".format(signature)) + + if signal.description is None or signal.description.strip() == '': + continue + f.write(rstize_text(signal.description.strip(), state)) + f.write("\n\n") + + # Enums + if len(class_def.enums) > 0: + f.write(make_heading('Enumerations', '-')) + for e in class_def.enums.values(): + f.write(".. _enum_{}_{}:\n\n".format(class_name, e.name)) + # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. + # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. + # As to why I'm not modifying the reference parser to directly link to the _enum label: + # If somebody gets annoyed enough to fix it, all existing references will magically improve. + for value in e.values.values(): + f.write(".. _class_{}_constant_{}:\n\n".format(class_name, value.name)) + + f.write("enum **{}**:\n\n".format(e.name)) + for value in e.values.values(): + f.write("- **{}** = **{}**".format(value.name, value.value)) + if value.text is not None and value.text.strip() != '': + f.write(' --- ' + rstize_text(value.text.strip(), state)) + f.write('\n\n') + + # Constants + if len(class_def.constants) > 0: + f.write(make_heading('Constants', '-')) + # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. + # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. + for constant in class_def.constants.values(): + f.write(".. _class_{}_constant_{}:\n\n".format(class_name, constant.name)) + + for constant in class_def.constants.values(): + f.write("- **{}** = **{}**".format(constant.name, constant.value)) + if constant.text is not None and constant.text.strip() != '': + f.write(' --- ' + rstize_text(constant.text.strip(), state)) + f.write('\n\n') + + # Class description + if class_def.description is not None and class_def.description.strip() != '': + f.write(make_heading('Description', '-')) + f.write(rstize_text(class_def.description.strip(), state) + "\n\n") + + # Online tutorials + if len(class_def.tutorials) > 0: + f.write(make_heading('Tutorials', '-')) + for t in class_def.tutorials: + link = t.strip() + match = GODOT_DOCS_PATTERN.search(link) + if match: + groups = match.groups() + if match.lastindex == 2: + # Doc reference with fragment identifier: emit direct link to section with reference to page, for example: + # `#calling-javascript-from-script in Exporting For Web` + f.write("- `" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`\n\n") + # Commented out alternative: Instead just emit: + # `Subsection in Exporting For Web` + # f.write("- `Subsection <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`\n\n") + elif match.lastindex == 1: + # Doc reference, for example: + # `Math` + f.write("- :doc:`../" + groups[0] + "`\n\n") + else: + # External link, for example: + # `http://enet.bespin.org/usergroup0.html` + f.write("- `" + link + " <" + link + ">`_\n\n") + + # Property descriptions + if len(class_def.properties) > 0: + f.write(make_heading('Property Descriptions', '-')) + for property_def in class_def.properties.values(): + #f.write(".. _class_{}_{}:\n\n".format(class_name, property_def.name)) + f.write(".. _class_{}_property_{}:\n\n".format(class_name, property_def.name)) + f.write('- {} **{}**\n\n'.format(property_def.type_name.to_rst(state), property_def.name)) + + setget = [] + if property_def.setter is not None and not property_def.setter.startswith("_"): + setget.append(("*Setter*", property_def.setter + '(value)')) + if property_def.getter is not None and not property_def.getter.startswith("_"): + setget.append(('*Getter*', property_def.getter + '()')) + + if len(setget) > 0: + format_table(f, setget) + + if property_def.text is not None and property_def.text.strip() != '': + f.write(rstize_text(property_def.text.strip(), state)) + f.write('\n\n') + + # Method descriptions + if len(class_def.methods) > 0: + f.write(make_heading('Method Descriptions', '-')) + for method_list in class_def.methods.values(): + for i, m in enumerate(method_list): + if i == 0: + #f.write(".. _class_{}_{}:\n\n".format(class_name, m.name)) + f.write(".. _class_{}_method_{}:\n\n".format(class_name, m.name)) + ret_type, signature = make_method_signature(class_def, m, False, state) + f.write("- {} {}\n\n".format(ret_type, signature)) + + if m.description is None or m.description.strip() == '': + continue + f.write(rstize_text(m.description.strip(), state)) + f.write("\n\n") + + +def make_class_list(class_list, columns): # type: (List[str], int) -> None + # This function is no longer used. + f = open('class_list.rst', 'w', encoding='utf-8') + col_max = len(class_list) // columns + 1 print(('col max is ', col_max)) - col_count = 0 - row_count = 0 - last_initial = '' - fit_columns = [] + fit_columns = [] # type: List[List[str]] - for n in range(0, columns): - fit_columns += [[]] + for _ in range(0, columns): + fit_columns.append([]) - indexers = [] + indexers = [] # type List[str] last_initial = '' - idx = 0 - for n in class_list: - col = idx / col_max + for idx, name in enumerate(class_list): + col = idx // col_max if col >= columns: col = columns - 1 - fit_columns[col] += [n] + fit_columns[col].append(name) idx += 1 - if n[:1] != last_initial: - indexers += [n] - last_initial = n[:1] + if name[:1] != last_initial: + indexers.append(name) + last_initial = name[:1] row_max = 0 f.write("\n") @@ -111,7 +601,7 @@ def make_class_list(class_list, columns): f.close() -def rstize_text(text, cclass): +def rstize_text(text, state): # type: (str, State) -> str # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock" pos = 0 while True: @@ -128,7 +618,8 @@ def rstize_text(text, cclass): if post_text.startswith("[codeblock]"): end_pos = post_text.find("[/codeblock]") if end_pos == -1: - sys.exit("ERROR! [codeblock] without a closing tag!") + print_error("[codeblock] without a closing tag, file: {}".format(state.current_class), state) + return "" code_text = post_text[len("[codeblock]"):end_pos] post_text = post_text[end_pos:] @@ -194,6 +685,7 @@ def rstize_text(text, cclass): # Handle [tags] inside_code = False pos = 0 + tag_depth = 0 while True: pos = text.find('[', pos) if pos == -1: @@ -209,53 +701,100 @@ def rstize_text(text, cclass): escape_post = False - if tag_text in class_names: - tag_text = make_type(tag_text) + if tag_text in state.classes: + tag_text = make_type(tag_text, state) escape_post = True else: # command cmd = tag_text space_pos = tag_text.find(' ') if cmd == '/codeblock': tag_text = '' + tag_depth -= 1 inside_code = False # Strip newline if the tag was alone on one if pre_text[-1] == '\n': pre_text = pre_text[:-1] elif cmd == '/code': tag_text = '``' + tag_depth -= 1 inside_code = False escape_post = True elif inside_code: tag_text = '[' + tag_text + ']' elif cmd.find('html') == 0: - cmd = tag_text[:space_pos] param = tag_text[space_pos + 1:] tag_text = param - elif cmd.find('method') == 0 or cmd.find('member') == 0 or cmd.find('signal') == 0: - cmd = tag_text[:space_pos] + elif cmd.startswith('method') or cmd.startswith('member') or cmd.startswith('signal') or cmd.startswith('constant'): param = tag_text[space_pos + 1:] if param.find('.') != -1: ss = param.split('.') if len(ss) > 2: - sys.exit("Bad reference: '" + param + "' in file: " + cur_file) - (class_param, method_param) = ss - tag_text = ':ref:`' + class_param + '.' + method_param + '<class_' + class_param + '_' + method_param + '>`' + print_error("Bad reference: '{}', file: {}".format(param, state.current_class), state) + class_param, method_param = ss + else: - tag_text = ':ref:`' + param + '<class_' + cclass + "_" + param + '>`' + class_param = state.current_class + method_param = param + + ref_type = "" + if class_param in state.classes: + class_def = state.classes[class_param] + if cmd.startswith("method"): + if method_param not in class_def.methods: + print_error("Unresolved method '{}', file: {}".format(param, state.current_class), state) + ref_type = "_method" + + elif cmd.startswith("member"): + if method_param not in class_def.properties: + print_error("Unresolved member '{}', file: {}".format(param, state.current_class), state) + ref_type = "_property" + + elif cmd.startswith("signal"): + if method_param not in class_def.signals: + print_error("Unresolved signal '{}', file: {}".format(param, state.current_class), state) + ref_type = "_signal" + + elif cmd.startswith("constant"): + found = False + if method_param in class_def.constants: + found = True + + else: + for enum in class_def.enums.values(): + if method_param in enum.values: + found = True + break + + if not found: + print_error("Unresolved constant '{}', file: {}".format(param, state.current_class), state) + ref_type = "_constant" + + else: + print_error("Unresolved type reference '{}' in method reference '{}', file: {}".format(class_param, param, state.current_class), state) + + repl_text = method_param + if class_param != state.current_class: + repl_text = "{}.{}".format(class_param, method_param) + tag_text = ':ref:`{}<class_{}{}_{}>`'.format(repl_text, class_param, ref_type, method_param) escape_post = True elif cmd.find('image=') == 0: tag_text = "" # '' elif cmd.find('url=') == 0: tag_text = ':ref:`' + cmd[4:] + '<' + cmd[4:] + ">`" + tag_depth += 1 elif cmd == '/url': tag_text = '' + tag_depth -= 1 escape_post = True elif cmd == 'center': + tag_depth += 1 tag_text = '' elif cmd == '/center': + tag_depth -= 1 tag_text = '' elif cmd == 'codeblock': + tag_depth += 1 tag_text = '\n::\n' inside_code = True elif cmd == 'br': @@ -265,22 +804,35 @@ def rstize_text(text, cclass): while post_text[0] == ' ': post_text = post_text[1:] elif cmd == 'i' or cmd == '/i': + if cmd == "/i": + tag_depth -= 1 + else: + tag_depth += 1 tag_text = '*' elif cmd == 'b' or cmd == '/b': + if cmd == "/b": + tag_depth -= 1 + else: + tag_depth += 1 tag_text = '**' elif cmd == 'u' or cmd == '/u': + if cmd == "/u": + tag_depth -= 1 + else: + tag_depth += 1 tag_text = '' elif cmd == 'code': tag_text = '``' + tag_depth += 1 inside_code = True elif cmd.startswith('enum '): - tag_text = make_enum(cmd[5:]) + tag_text = make_enum(cmd[5:], state) else: - tag_text = make_type(tag_text) + tag_text = make_type(tag_text, state) escape_post = True # Properly escape things like `[Node]s` - if escape_post and post_text and post_text[0].isalnum(): # not punctuation, escape + if escape_post and post_text and (post_text[0].isalnum() or post_text[0] == "("): # not punctuation, escape post_text = '\ ' + post_text next_brac_pos = post_text.find('[', 0) @@ -306,20 +858,52 @@ def rstize_text(text, cclass): text = pre_text + tag_text + post_text pos = len(pre_text) + len(tag_text) + if tag_depth > 0: + print_error("Tag depth mismatch: too many/little open/close tags, file: {}".format(state.current_class), state) + return text -def make_type(t): - global class_names - if t in class_names: - return ':ref:`' + t + '<class_' + t.lower() + '>`' +def format_table(f, pp): # type: (TextIO, Iterable[Tuple[str, ...]]) -> None + longest_t = 0 + longest_s = 0 + for s in pp: + sl = len(s[0]) + if sl > longest_s: + longest_s = sl + tl = len(s[1]) + if tl > longest_t: + longest_t = tl + + sep = "+" + for i in range(longest_s + 2): + sep += "-" + sep += "+" + for i in range(longest_t + 2): + sep += "-" + sep += "+\n" + f.write(sep) + for s in pp: + rt = s[0] + while len(rt) < longest_s: + rt += " " + st = s[1] + while len(st) < longest_t: + st += " " + f.write("| " + rt + " | " + st + " |\n") + f.write(sep) + f.write('\n') + + +def make_type(t, state): # type: (str, State) -> str + if t in state.classes: + return ':ref:`{0}<class_{0}>`'.format(t) + print_error("Unresolved type '{}', file: {}".format(t, state.current_class), state) return t -def make_enum(t): - global class_names +def make_enum(t, state): # type: (str, State) -> str p = t.find(".") - # Global enums such as Error are relative to @GlobalScope. if p >= 0: c = t[0:p] e = t[p + 1:] @@ -328,346 +912,61 @@ def make_enum(t): c = "@GlobalScope" e = "Variant." + e else: - # Things in GlobalScope don't have a period. - c = "@GlobalScope" + c = state.current_class e = t - if c in class_names: - return ':ref:`' + e + '<enum_' + c.lower() + '_' + e.lower() + '>`' - return t + if c in state.classes and e not in state.classes[c].enums: + c = "@GlobalScope" + if c in state.classes and e in state.classes[c].enums: + return ":ref:`{0}<enum_{1}_{0}>`".format(e, c) + print_error("Unresolved enum '{}', file: {}".format(t, state.current_class), state) + return t -def make_method( - f, - name, - m, - declare, - cname, - event=False, - pp=None -): - if (declare or pp == None): - t = '- ' - else: - t = "" - - ret_type = 'void' - args = list(m) - mdata = {} - mdata['argidx'] = [] - for a in args: - if a.tag == 'return': - idx = -1 - elif a.tag == 'argument': - idx = int(a.attrib['index']) - else: - continue - mdata['argidx'].append(idx) - mdata[idx] = a +def make_method_signature(class_def, method_def, make_ref, state): # type: (ClassDef, Union[MethodDef, SignalDef], bool, State) -> Tuple[str, str] + ret_type = " " - if not event: - if -1 in mdata['argidx']: - if 'enum' in mdata[-1].attrib: - t += make_enum(mdata[-1].attrib['enum']) - else: - t += make_type(mdata[-1].attrib['type']) - else: - t += 'void' - t += ' ' + ref_type = "signal" + if isinstance(method_def, MethodDef): + ret_type = method_def.return_type.to_rst(state) + ref_type = "method" - if declare or pp == None: + out = "" - s = '**' + m.attrib['name'] + '** ' + if make_ref: + out += ":ref:`{0}<class_{1}_{2}_{0}>` ".format(method_def.name, class_def.name, ref_type) else: - s = ':ref:`' + m.attrib['name'] + '<class_' + cname + "_" + m.attrib['name'] + '>` ' + out += "**{}** ".format(method_def.name) - s += '**(**' - argfound = False - for a in mdata['argidx']: - arg = mdata[a] - if a < 0: - continue - if a > 0: - s += ', ' + out += '**(**' + for i, arg in enumerate(method_def.parameters): + if i > 0: + out += ', ' else: - s += ' ' + out += ' ' - if 'enum' in arg.attrib: - s += make_enum(arg.attrib['enum']) - else: - s += make_type(arg.attrib['type']) - if 'name' in arg.attrib: - s += ' ' + arg.attrib['name'] - else: - s += ' arg' + str(a) - - if 'default' in arg.attrib: - s += '=' + arg.attrib['default'] + out += "{} {}".format(arg.type_name.to_rst(state), arg.name) - s += ' **)**' + if arg.default_value is not None: + out += '=' + arg.default_value - if 'qualifiers' in m.attrib: - s += ' ' + m.attrib['qualifiers'] - - if (not declare): - if (pp != None): - pp.append((t, s)) + if isinstance(method_def, MethodDef) and method_def.qualifiers is not None and 'vararg' in method_def.qualifiers: + if len(method_def.parameters) > 0: + out += ', ...' else: - f.write("- " + t + " " + s + "\n") - else: - f.write(t + s + "\n") - - -def make_heading(title, underline): - return title + '\n' + underline * len(title) + "\n\n" - - -def make_rst_class(node): - name = node.attrib['name'] - - f = codecs.open("class_" + name.lower() + '.rst', 'wb', 'utf-8') - - # Warn contributors not to edit this file directly - f.write(".. Generated automatically by doc/tools/makerst.py in Godot's source tree.\n") - f.write(".. DO NOT EDIT THIS FILE, but the " + name + ".xml source instead.\n") - f.write(".. The source is found in doc/classes or modules/<name>/doc_classes.\n\n") - - f.write(".. _class_" + name + ":\n\n") - f.write(make_heading(name, '=')) - - if 'inherits' in node.attrib: - inh = node.attrib['inherits'].strip() - f.write('**Inherits:** ') - first = True - while (inh in classes): - if (not first): - f.write(" **<** ") - else: - first = False - - f.write(make_type(inh)) - inode = classes[inh] - if ('inherits' in inode.attrib): - inh = inode.attrib['inherits'].strip() - else: - inh = None - - f.write("\n\n") - - inherited = [] - for cn in classes: - c = classes[cn] - if 'inherits' in c.attrib: - if (c.attrib['inherits'].strip() == name): - inherited.append(c.attrib['name']) - - if (len(inherited)): - f.write('**Inherited By:** ') - for i in range(len(inherited)): - if (i > 0): - f.write(", ") - f.write(make_type(inherited[i])) - f.write("\n\n") - if 'category' in node.attrib: - f.write('**Category:** ' + node.attrib['category'].strip() + "\n\n") - - f.write(make_heading('Brief Description', '-')) - briefd = node.find('brief_description') - if briefd != None: - f.write(rstize_text(briefd.text.strip(), name) + "\n\n") - - methods = node.find('methods') - - if methods != None and len(list(methods)) > 0: - f.write(make_heading('Member Functions', '-')) - ml = [] - for m in list(methods): - make_method(f, node.attrib['name'], m, False, name, False, ml) - longest_t = 0 - longest_s = 0 - for s in ml: - sl = len(s[0]) - if (sl > longest_s): - longest_s = sl - tl = len(s[1]) - if (tl > longest_t): - longest_t = tl - - sep = "+" - for i in range(longest_s + 2): - sep += "-" - sep += "+" - for i in range(longest_t + 2): - sep += "-" - sep += "+\n" - f.write(sep) - for s in ml: - rt = s[0] - while (len(rt) < longest_s): - rt += " " - st = s[1] - while (len(st) < longest_t): - st += " " - f.write("| " + rt + " | " + st + " |\n") - f.write(sep) - f.write('\n') - - events = node.find('signals') - if events != None and len(list(events)) > 0: - f.write(make_heading('Signals', '-')) - for m in list(events): - f.write(".. _class_" + name + "_" + m.attrib['name'] + ":\n\n") - make_method(f, node.attrib['name'], m, True, name, True) - f.write('\n') - d = m.find('description') - if d == None or d.text.strip() == '': - continue - f.write(rstize_text(d.text.strip(), name)) - f.write("\n\n") - - f.write('\n') - - members = node.find('members') - if members != None and len(list(members)) > 0: - f.write(make_heading('Member Variables', '-')) - - for c in list(members): - # Leading two spaces necessary to prevent breaking the <ul> - f.write(" .. _class_" + name + "_" + c.attrib['name'] + ":\n\n") - s = '- ' - if 'enum' in c.attrib: - s += make_enum(c.attrib['enum']) + ' ' - else: - s += make_type(c.attrib['type']) + ' ' - s += '**' + c.attrib['name'] + '**' - if c.text.strip() != '': - s += ' - ' + rstize_text(c.text.strip(), name) - f.write(s + '\n\n') - f.write('\n') - - constants = node.find('constants') - consts = [] - enum_names = set() - enums = [] - if constants != None and len(list(constants)) > 0: - for c in list(constants): - if 'enum' in c.attrib: - enum_names.add(c.attrib['enum']) - enums.append(c) - else: - consts.append(c) - - if len(consts) > 0: - f.write(make_heading('Numeric Constants', '-')) - for c in list(consts): - s = '- ' - s += '**' + c.attrib['name'] + '**' - if 'value' in c.attrib: - s += ' = **' + c.attrib['value'] + '**' - if c.text.strip() != '': - s += ' --- ' + rstize_text(c.text.strip(), name) - f.write(s + '\n') - f.write('\n') - - if len(enum_names) > 0: - f.write(make_heading('Enums', '-')) - for e in enum_names: - f.write(" .. _enum_" + name + "_" + e + ":\n\n") - f.write("enum **" + e + "**\n\n") - for c in enums: - if c.attrib['enum'] != e: - continue - s = '- ' - s += '**' + c.attrib['name'] + '**' - if 'value' in c.attrib: - s += ' = **' + c.attrib['value'] + '**' - if c.text.strip() != '': - s += ' --- ' + rstize_text(c.text.strip(), name) - f.write(s + '\n') - f.write('\n') - f.write('\n') - - descr = node.find('description') - if descr != None and descr.text.strip() != '': - f.write(make_heading('Description', '-')) - f.write(rstize_text(descr.text.strip(), name) + "\n\n") - - global godot_docs_pattern - tutorials = node.find('tutorials') - if tutorials != None and len(tutorials) > 0: - f.write(make_heading('Tutorials', '-')) - for t in tutorials: - link = t.text.strip() - match = godot_docs_pattern.search(link); - if match: - groups = match.groups() - if match.lastindex == 2: - # Doc reference with fragment identifier: emit direct link to section with reference to page, for example: - # `#calling-javascript-from-script in Exporting For Web` - f.write("- `" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`\n") - # Commented out alternative: Instead just emit: - # `Subsection in Exporting For Web` - # f.write("- `Subsection <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`\n") - elif match.lastindex == 1: - # Doc reference, for example: - # `Math` - f.write("- :doc:`../" + groups[0] + "`\n") - else: - # External link, for example: - # `http://enet.bespin.org/usergroup0.html` - f.write("- `" + link + " <" + link + ">`_\n") - f.write("\n") - - methods = node.find('methods') - if methods != None and len(list(methods)) > 0: - f.write(make_heading('Member Function Description', '-')) - for m in list(methods): - f.write(".. _class_" + name + "_" + m.attrib['name'] + ":\n\n") - make_method(f, node.attrib['name'], m, True, name) - f.write('\n') - d = m.find('description') - if d == None or d.text.strip() == '': - continue - f.write(rstize_text(d.text.strip(), name)) - f.write("\n\n") - f.write('\n') - - f.close() - - -file_list = [] + out += '...' -for path in input_list: - if os.path.basename(path) == 'modules': - for subdir, dirs, _ in os.walk(path): - if 'doc_classes' in dirs: - doc_dir = os.path.join(subdir, 'doc_classes') - class_file_names = [f for f in os.listdir(doc_dir) if f.endswith('.xml')] - file_list += [os.path.join(doc_dir, f) for f in class_file_names] - elif not os.path.isfile(path): - file_list += [os.path.join(path, f) for f in os.listdir(path) if f.endswith('.xml')] - elif os.path.isfile(path) and path.endswith('.xml'): - file_list.append(path) + out += ' **)**' -for cur_file in file_list: - tree = ET.parse(cur_file) - doc = tree.getroot() + if isinstance(method_def, MethodDef) and method_def.qualifiers is not None: + out += ' ' + method_def.qualifiers - if 'version' not in doc.attrib: - print("Version missing from 'doc'") - sys.exit(255) + return ret_type, out - 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() +def make_heading(title, underline): # type: (str, str) -> str + return title + '\n' + (underline * len(title)) + "\n\n" -# Don't make class list for Sphinx, :toctree: handles it -# make_class_list(class_names, 2) -for cn in class_names: - c = classes[cn] - make_rst_class(c) +if __name__ == '__main__': + main() |