diff options
Diffstat (limited to 'doc/tools/makerst.py')
| -rw-r--r-- | doc/tools/makerst.py | 85 |
1 files changed, 78 insertions, 7 deletions
diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py index dc015d781b..8074ce45ea 100644 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -7,6 +7,7 @@ import os import xml.etree.ElementTree as ET input_list = [] +cur_file = "" for arg in sys.argv[1:]: if arg.endswith(os.sep): @@ -103,6 +104,7 @@ def make_class_list(class_list, columns): f.write("--+-------+") f.write("\n") + f.close() def rstize_text(text, cclass): # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock" @@ -154,8 +156,9 @@ def rstize_text(text, cclass): # Escape * character to avoid interpreting it as emphasis pos = 0 + next_brac_pos = text.find('['); while True: - pos = text.find('*', pos) + pos = text.find('*', pos, next_brac_pos) if pos == -1: break text = text[:pos] + "\*" + text[pos + 1:] @@ -164,7 +167,7 @@ def rstize_text(text, cclass): # Escape _ character at the end of a word to avoid interpreting it as an inline hyperlink pos = 0 while True: - pos = text.find('_', pos) + pos = text.find('_', pos, next_brac_pos) if pos == -1: break if not text[pos + 1].isalnum(): # don't escape within a snake_case word @@ -206,6 +209,7 @@ def rstize_text(text, cclass): elif cmd == '/code': tag_text = '``' inside_code = False + escape_post = True elif inside_code: tag_text = '[' + tag_text + ']' elif cmd.find('html') == 0: @@ -217,7 +221,10 @@ def rstize_text(text, cclass): param = tag_text[space_pos + 1:] if param.find('.') != -1: - (class_param, method_param) = param.split('.') + 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 + '>`' else: tag_text = ':ref:`' + param + '<class_' + cclass + "_" + param + '>`' @@ -259,6 +266,27 @@ def rstize_text(text, cclass): if escape_post and post_text and post_text[0].isalnum(): # not punctuation, escape post_text = '\ ' + post_text + next_brac_pos = post_text.find('[',0) + iter_pos = 0 + while not inside_code: + iter_pos = post_text.find('*', iter_pos, next_brac_pos) + if iter_pos == -1: + break + post_text = post_text[:iter_pos] + "\*" + post_text[iter_pos + 1:] + iter_pos += 2 + + iter_pos = 0 + while not inside_code: + iter_pos = post_text.find('_', iter_pos, next_brac_pos) + if iter_pos == -1: + break + if not post_text[iter_pos + 1].isalnum(): # don't escape within a snake_case word + post_text = post_text[:iter_pos] + "\_" + post_text[iter_pos + 1:] + iter_pos += 2 + else: + iter_pos += 1 + + text = pre_text + tag_text + post_text pos = len(pre_text) + len(tag_text) @@ -271,6 +299,15 @@ def make_type(t): return ':ref:`' + t + '<class_' + t.lower() + '>`' return t +def make_enum(t): + global class_names + p = t.find(".") + if p >= 0: + c = t[0:p] + e = t[p+1:] + if c in class_names: + return ':ref:`' + e + '<enum_' + c.lower() + '_' + e.lower() + '>`' + return t def make_method( f, @@ -465,7 +502,10 @@ def make_rst_class(node): # Leading two spaces necessary to prevent breaking the <ul> f.write(" .. _class_" + name + "_" + c.attrib['name'] + ":\n\n") s = '- ' - s += make_type(c.attrib['type']) + ' ' + 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) @@ -473,9 +513,20 @@ def make_rst_class(node): f.write('\n') constants = node.find('constants') + consts = [] + enum_names = set() + enums = [] if constants != None and len(list(constants)) > 0: - f.write(make_heading('Numeric Constants', '-')) 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: @@ -485,6 +536,24 @@ def make_rst_class(node): 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', '-')) @@ -504,6 +573,8 @@ def make_rst_class(node): f.write("\n\n") f.write('\n') + f.close() + file_list = [] @@ -519,8 +590,8 @@ for path in input_list: elif os.path.isfile(path) and path.endswith('.xml'): file_list.append(path) -for file in file_list: - tree = ET.parse(file) +for cur_file in file_list: + tree = ET.parse(cur_file) doc = tree.getroot() if 'version' not in doc.attrib: |