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 | 239 |
4 files changed, 146 insertions, 459 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..7b7cc52547 100755 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -309,10 +309,41 @@ def rstize_text(text, cclass): return text +def format_table(f, pp): + 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): global class_names if t in class_names: - return ':ref:`' + t + '<class_' + t.lower() + '>`' + return ':ref:`' + t + '<class_' + t + '>`' return t @@ -332,26 +363,25 @@ def make_enum(t): c = "@GlobalScope" e = t if c in class_names: - return ':ref:`' + e + '<enum_' + c.lower() + '_' + e.lower() + '>`' + return ':ref:`' + e + '<enum_' + c + '_' + e + '>`' return t def make_method( f, - name, - m, - declare, cname, + method_data, + declare, event=False, pp=None ): - if (declare or pp == None): + if (declare or pp is None): t = '- ' else: t = "" ret_type = 'void' - args = list(m) + args = list(method_data) mdata = {} mdata['argidx'] = [] for a in args: @@ -375,11 +405,11 @@ def make_method( t += 'void' t += ' ' - if declare or pp == None: + if declare or pp is None: - s = '**' + m.attrib['name'] + '** ' + s = '**' + method_data.attrib['name'] + '** ' else: - s = ':ref:`' + m.attrib['name'] + '<class_' + cname + "_" + m.attrib['name'] + '>` ' + s = ':ref:`' + method_data.attrib['name'] + '<class_' + cname + "_" + method_data.attrib['name'] + '>` ' s += '**(**' argfound = False @@ -406,8 +436,8 @@ def make_method( s += ' **)**' - if 'qualifiers' in m.attrib: - s += ' ' + m.attrib['qualifiers'] + if 'qualifiers' in method_data.attrib: + s += ' ' + method_data.attrib['qualifiers'] if (not declare): if (pp != None): @@ -418,6 +448,37 @@ def make_method( f.write(t + s + "\n") +def make_properties( + f, + cname, + prop_data, + description=False, + pp=None +): + t = "" + if 'enum' in prop_data.attrib: + t += make_enum(prop_data.attrib['enum']) + else: + t += make_type(prop_data.attrib['type']) + + if description: + s = '**' + prop_data.attrib['name'] + '**' + setget = [] + if 'setter' in prop_data.attrib and prop_data.attrib['setter'] != '' and not prop_data.attrib['setter'].startswith('_'): + setget.append(("*Setter*", prop_data.attrib['setter'] + '(value)')) + if 'getter' in prop_data.attrib and prop_data.attrib['getter'] != '' and not prop_data.attrib['getter'].startswith('_'): + setget.append(('*Getter*', prop_data.attrib['getter'] + '()')) + else: + s = ':ref:`' + prop_data.attrib['name'] + '<class_' + cname + "_" + prop_data.attrib['name'] + '>`' + + if (pp != None): + pp.append((t, s)) + elif description: + f.write('- ' + t + ' ' + s + '\n\n') + if len(setget) > 0: + format_table(f, setget) + + def make_heading(title, underline): return title + '\n' + underline * len(title) + "\n\n" @@ -435,6 +496,8 @@ def make_rst_class(node): f.write(".. _class_" + name + ":\n\n") f.write(make_heading(name, '=')) + # Inheritance tree + # Ascendents if 'inherits' in node.attrib: inh = node.attrib['inherits'].strip() f.write('**Inherits:** ') @@ -451,16 +514,15 @@ def make_rst_class(node): inh = inode.attrib['inherits'].strip() else: inh = None - f.write("\n\n") + # Descendents 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)): @@ -468,83 +530,59 @@ def make_rst_class(node): f.write(", ") f.write(make_type(inherited[i])) f.write("\n\n") + + # Category if 'category' in node.attrib: f.write('**Category:** ' + node.attrib['category'].strip() + "\n\n") + # Brief description 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') + # Properties overview + members = node.find('members') + if members != None and len(list(members)) > 0: + f.write(make_heading('Properties', '-')) + ml = [] + for m in list(members): + make_properties(f, name, m, False, ml) + format_table(f, ml) + # Methods overview + methods = node.find('methods') if methods != None and len(list(methods)) > 0: - f.write(make_heading('Member Functions', '-')) + f.write(make_heading('Methods', '-')) 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') + make_method(f, name, m, False, False, ml) + format_table(f, ml) + # Theme properties + theme_items = node.find('theme_items') + if theme_items != None and len(list(theme_items)) > 0: + f.write(make_heading('Theme Properties', '-')) + ml = [] + for m in list(theme_items): + make_properties(f, name, m, False, ml) + format_table(f, ml) + + # Signals 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) + make_method(f, name, m, True, True) f.write('\n') d = m.find('description') - if d == None or d.text.strip() == '': + if d is 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 and enums constants = node.find('constants') consts = [] enum_names = set() @@ -557,23 +595,12 @@ def make_rst_class(node): 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') - + # Enums if len(enum_names) > 0: - f.write(make_heading('Enums', '-')) + f.write(make_heading('Enumerations', '-')) for e in enum_names: - f.write(" .. _enum_" + name + "_" + e + ":\n\n") - f.write("enum **" + e + "**\n\n") + f.write(".. _enum_" + name + "_" + e + ":\n\n") + f.write("enum **" + e + "**:\n\n") for c in enums: if c.attrib['enum'] != e: continue @@ -583,15 +610,27 @@ def make_rst_class(node): 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') + f.write(s + '\n\n') + # Constants + if len(consts) > 0: + f.write(make_heading('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\n') + + # Class description 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") + # Online tutorials global godot_docs_pattern tutorials = node.find('tutorials') if tutorials != None and len(tutorials) > 0: @@ -604,35 +643,43 @@ def make_rst_class(node): 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") + 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") + # 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") + f.write("- :doc:`../" + groups[0] + "`\n\n") else: # External link, for example: # `http://enet.bespin.org/usergroup0.html` - f.write("- `" + link + " <" + link + ">`_\n") - f.write("\n") + f.write("- `" + link + " <" + link + ">`_\n\n") + # Property descriptions + members = node.find('members') + if members != None and len(list(members)) > 0: + f.write(make_heading('Property Descriptions', '-')) + for m in list(members): + f.write(".. _class_" + name + "_" + m.attrib['name'] + ":\n\n") + make_properties(f, name, m, True) + if m.text.strip() != '': + f.write(rstize_text(m.text.strip(), name)) + f.write('\n\n') + + # Method descriptions methods = node.find('methods') if methods != None and len(list(methods)) > 0: - f.write(make_heading('Member Function Description', '-')) + f.write(make_heading('Method Descriptions', '-')) for m in list(methods): f.write(".. _class_" + name + "_" + m.attrib['name'] + ":\n\n") - make_method(f, node.attrib['name'], m, True, name) + make_method(f, name, m, True) f.write('\n') d = m.find('description') - if d == None or d.text.strip() == '': + if d is 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 = [] |