diff options
Diffstat (limited to 'doc/tools/makerst.py')
| -rwxr-xr-x[-rw-r--r--] | doc/tools/makerst.py | 77 |
1 files changed, 68 insertions, 9 deletions
diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py index 8074ce45ea..93ad823d42 100644..100755 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -4,11 +4,15 @@ import codecs import sys import os +import re import xml.etree.ElementTree as ET input_list = [] cur_file = "" +# 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(#.*)?$') + for arg in sys.argv[1:]: if arg.endswith(os.sep): arg = arg[:-1] @@ -106,6 +110,7 @@ def make_class_list(class_list, columns): f.close() + def rstize_text(text, cclass): # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock" pos = 0 @@ -154,9 +159,19 @@ def rstize_text(text, cclass): text = pre_text + "\n\n" + post_text pos += 2 + next_brac_pos = text.find('[') + + # Escape \ character, otherwise it ends up as an escape character in rst + pos = 0 + while True: + pos = text.find('\\', pos, next_brac_pos) + if pos == -1: + break + text = text[:pos] + "\\\\" + text[pos + 1:] + pos += 2 + # Escape * character to avoid interpreting it as emphasis pos = 0 - next_brac_pos = text.find('['); while True: pos = text.find('*', pos, next_brac_pos) if pos == -1: @@ -258,15 +273,17 @@ def rstize_text(text, cclass): elif cmd == 'code': tag_text = '``' inside_code = True + elif cmd.startswith('enum '): + tag_text = make_enum(cmd[5:]) else: tag_text = make_type(tag_text) 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(): # not punctuation, escape post_text = '\ ' + post_text - next_brac_pos = post_text.find('[',0) + next_brac_pos = post_text.find('[', 0) iter_pos = 0 while not inside_code: iter_pos = post_text.find('*', iter_pos, next_brac_pos) @@ -286,7 +303,6 @@ def rstize_text(text, cclass): else: iter_pos += 1 - text = pre_text + tag_text + post_text pos = len(pre_text) + len(tag_text) @@ -299,16 +315,27 @@ def make_type(t): return ':ref:`' + t + '<class_' + t.lower() + '>`' return t + def make_enum(t): global class_names p = t.find(".") + # Global enums such as Error are relative to @GlobalScope. if p >= 0: c = t[0:p] - e = t[p+1:] - if c in class_names: - return ':ref:`' + e + '<enum_' + c.lower() + '_' + e.lower() + '>`' + e = t[p + 1:] + # Variant enums live in GlobalScope but still use periods. + if c == "Variant": + c = "@GlobalScope" + e = "Variant." + e + else: + # Things in GlobalScope don't have a period. + c = "@GlobalScope" + e = t + if c in class_names: + return ':ref:`' + e + '<enum_' + c.lower() + '_' + e.lower() + '>`' return t + def make_method( f, name, @@ -340,7 +367,10 @@ def make_method( if not event: if -1 in mdata['argidx']: - t += make_type(mdata[-1].attrib['type']) + 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 += ' ' @@ -362,7 +392,10 @@ def make_method( else: s += ' ' - s += make_type(arg.attrib['type']) + 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: @@ -559,6 +592,32 @@ def make_rst_class(node): 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', '-')) |