diff options
Diffstat (limited to 'doc/tools')
| -rwxr-xr-x | doc/tools/doc_status.py | 32 | ||||
| -rwxr-xr-x | doc/tools/make_rst.py | 1685 | ||||
| -rwxr-xr-x | doc/tools/makerst.py | 1135 |
3 files changed, 1707 insertions, 1145 deletions
diff --git a/doc/tools/doc_status.py b/doc/tools/doc_status.py index 629b5a032b..cc0733cab2 100755 --- a/doc/tools/doc_status.py +++ b/doc/tools/doc_status.py @@ -66,10 +66,23 @@ table_columns = [ "methods", "constants", "members", - "signals", "theme_items", + "signals", + "operators", + "constructors", +] +table_column_names = [ + "Name", + "Brief Desc.", + "Desc.", + "Methods", + "Constants", + "Members", + "Theme Items", + "Signals", + "Operators", + "Constructors", ] -table_column_names = ["Name", "Brief Desc.", "Desc.", "Methods", "Constants", "Members", "Signals", "Theme Items"] colors = { "name": [36], # cyan "part_big_problem": [4, 31], # underline, red @@ -82,7 +95,7 @@ colors = { "state_on": [1, 35], # bold, magenta/plum "bold": [1], # bold } -overall_progress_description_weigth = 10 +overall_progress_description_weight = 10 ################################################################################ @@ -180,6 +193,8 @@ class ClassStatus: "members": ClassStatusProgress(), "theme_items": ClassStatusProgress(), "signals": ClassStatusProgress(), + "operators": ClassStatusProgress(), + "constructors": ClassStatusProgress(), } def __add__(self, other): @@ -218,12 +233,12 @@ class ClassStatus: 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, + (self.has_brief_description + self.has_description) * overall_progress_description_weight, + 2 * overall_progress_description_weight, ) items_progress = ClassStatusProgress() - for k in ["methods", "constants", "members", "signals", "theme_items"]: + for k in ["methods", "constants", "members", "theme_items", "signals", "constructors", "operators"]: items_progress += self.progresses[k] output[k] = self.progresses[k].to_configured_colored_string() @@ -260,7 +275,7 @@ class ClassStatus: elif tag.tag == "description": status.has_description = len(tag.text.strip()) > 0 - elif tag.tag in ["methods", "signals"]: + elif tag.tag in ["methods", "signals", "operators", "constructors"]: for sub_tag in list(tag): descr = sub_tag.find("description") status.progresses[tag.tag].increment(len(descr.text.strip()) > 0) @@ -272,9 +287,6 @@ class ClassStatus: 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) diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py new file mode 100755 index 0000000000..207eb7fabd --- /dev/null +++ b/doc/tools/make_rst.py @@ -0,0 +1,1685 @@ +#!/usr/bin/env python3 + +# This script makes RST files from the XML class reference for use with the online docs. + +import argparse +import os +import platform +import re +import sys +import xml.etree.ElementTree as ET +from collections import OrderedDict +from typing import List, Dict, TextIO, Tuple, Optional, Any, Union + +# Import hardcoded version information from version.py +root_directory = os.path.join(os.path.dirname(os.path.abspath(__file__)), "../../") +sys.path.append(root_directory) # Include the root directory +import version + +# $DOCS_URL/path/to/page.html(#fragment-tag) +GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$") + +# Based on reStructedText inline markup recognition rules +# https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules +MARKUP_ALLOWED_PRECEDENT = " -:/'\"<([{" +MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>" + +# Used to translate section headings and other hardcoded strings when required with +# the --lang argument. The BASE_STRINGS list should be synced with what we actually +# write in this script (check `translate()` uses), and also hardcoded in +# `doc/translations/extract.py` to include them in the source POT file. +BASE_STRINGS = [ + "Description", + "Tutorials", + "Properties", + "Constructors", + "Methods", + "Operators", + "Theme Properties", + "Signals", + "Enumerations", + "Constants", + "Annotations", + "Property Descriptions", + "Constructor Descriptions", + "Method Descriptions", + "Operator Descriptions", + "Theme Property Descriptions", + "Inherits:", + "Inherited By:", + "(overrides %s)", + "Default", + "Setter", + "value", + "Getter", + "This method should typically be overridden by the user to have any effect.", + "This method has no side effects. It doesn't modify any of the instance's member variables.", + "This method accepts any number of arguments after the ones described here.", + "This method is used to construct a type.", + "This method doesn't need an instance to be called, so it can be called directly using the class name.", + "This method describes a valid operator to use with this type as left-hand operand.", +] +strings_l10n: Dict[str, str] = {} + +STYLES: Dict[str, str] = {} + + +class State: + def __init__(self) -> None: + self.num_errors = 0 + self.classes: OrderedDict[str, ClassDef] = OrderedDict() + self.current_class: str = "" + + def parse_class(self, class_root: ET.Element, filepath: str) -> None: + class_name = class_root.attrib["name"] + self.current_class = class_name + + class_def = ClassDef(class_name) + self.classes[class_name] = class_def + class_def.filepath = filepath + + inherits = class_root.get("inherits") + if inherits is not None: + class_def.inherits = inherits + + 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('{}.xml: Duplicate property "{}".'.format(class_name, property_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 + default_value = property.get("default") or None + if default_value is not None: + default_value = "``{}``".format(default_value) + overrides = property.get("overrides") or None + + property_def = PropertyDef( + property_name, type_name, setter, getter, property.text, default_value, overrides + ) + class_def.properties[property_name] = property_def + + constructors = class_root.find("constructors") + if constructors is not None: + for constructor in constructors: + assert constructor.tag == "constructor" + + method_name = constructor.attrib["name"] + qualifiers = constructor.get("qualifiers") + + return_element = constructor.find("return") + if return_element is not None: + return_type = TypeName.from_element(return_element) + else: + return_type = TypeName("void") + + params = self.parse_params(constructor, "constructor") + + desc_element = constructor.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) + method_def.definition_name = "constructor" + if method_name not in class_def.constructors: + class_def.constructors[method_name] = [] + + class_def.constructors[method_name].append(method_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 = self.parse_params(method, "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) + + operators = class_root.find("operators") + if operators is not None: + for operator in operators: + assert operator.tag == "operator" + + method_name = operator.attrib["name"] + qualifiers = operator.get("qualifiers") + + return_element = operator.find("return") + if return_element is not None: + return_type = TypeName.from_element(return_element) + + else: + return_type = TypeName("void") + + params = self.parse_params(operator, "operator") + + desc_element = operator.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) + method_def.definition_name = "operator" + if method_name not in class_def.operators: + class_def.operators[method_name] = [] + + class_def.operators[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") + is_bitfield = constant.get("is_bitfield") == "true" + constant_def = ConstantDef(constant_name, value, constant.text, is_bitfield) + if enum is None: + if constant_name in class_def.constants: + print_error('{}.xml: Duplicate constant "{}".'.format(class_name, constant_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, is_bitfield) + class_def.enums[enum] = enum_def + + enum_def.values[constant_name] = constant_def + + annotations = class_root.find("annotations") + if annotations is not None: + for annotation in annotations: + assert annotation.tag == "annotation" + + annotation_name = annotation.attrib["name"] + qualifiers = annotation.get("qualifiers") + + params = self.parse_params(annotation, "annotation") + + desc_element = annotation.find("description") + annotation_desc = None + if desc_element is not None: + annotation_desc = desc_element.text + + annotation_def = AnnotationDef(annotation_name, params, annotation_desc, qualifiers) + if annotation_name not in class_def.annotations: + class_def.annotations[annotation_name] = [] + + class_def.annotations[annotation_name].append(annotation_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('{}.xml: Duplicate signal "{}".'.format(class_name, signal_name), self) + continue + + params = self.parse_params(signal, "signal") + + desc_element = signal.find("description") + signal_desc = None + if desc_element is not None: + signal_desc = desc_element.text + + 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: + for theme_item in theme_items: + assert theme_item.tag == "theme_item" + + theme_item_name = theme_item.attrib["name"] + theme_item_data_name = theme_item.attrib["data_type"] + theme_item_id = "{}_{}".format(theme_item_data_name, theme_item_name) + if theme_item_id in class_def.theme_items: + print_error( + '{}.xml: Duplicate theme item "{}" of type "{}".'.format( + class_name, theme_item_name, theme_item_data_name + ), + self, + ) + continue + + default_value = theme_item.get("default") or None + if default_value is not None: + default_value = "``{}``".format(default_value) + + theme_item_def = ThemeItemDef( + theme_item_name, + TypeName.from_element(theme_item), + theme_item_data_name, + theme_item.text, + default_value, + ) + class_def.theme_items[theme_item_name] = 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.strip(), link.get("title", ""))) + + self.current_class = "" + + def parse_params(self, root: ET.Element, context: str) -> List["ParameterDef"]: + param_elements = root.findall("param") + params: Any = [None] * len(param_elements) + + for param_index, param_element in enumerate(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") + + if param_name.strip() == "" or param_name.startswith("_unnamed_arg"): + print_error( + '{}.xml: Empty argument name in {} "{}" at position {}.'.format( + self.current_class, context, root.attrib["name"], param_index + ), + self, + ) + + params[index] = ParameterDef(param_name, type_name, default) + + cast: List[ParameterDef] = params + + return cast + + def sort_classes(self) -> None: + self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0])) + + +class TypeName: + def __init__(self, type_name: str, enum: Optional[str] = None) -> None: + self.type_name = type_name + self.enum = enum + + def to_rst(self, state: 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: ET.Element) -> "TypeName": + return cls(element.attrib["type"], element.get("enum")) + + +class PropertyDef: + def __init__( + self, + name: str, + type_name: TypeName, + setter: Optional[str], + getter: Optional[str], + text: Optional[str], + default_value: Optional[str], + overrides: Optional[str], + ) -> None: + self.definition_name = "property" + + self.name = name + self.type_name = type_name + self.setter = setter + self.getter = getter + self.text = text + self.default_value = default_value + self.overrides = overrides + + +class ParameterDef: + def __init__(self, name: str, type_name: TypeName, default_value: Optional[str]) -> None: + self.definition_name = "parameter" + + self.name = name + self.type_name = type_name + self.default_value = default_value + + +class SignalDef: + def __init__(self, name: str, parameters: List[ParameterDef], description: Optional[str]) -> None: + self.definition_name = "signal" + + self.name = name + self.parameters = parameters + self.description = description + + +class AnnotationDef: + def __init__( + self, + name: str, + parameters: List[ParameterDef], + description: Optional[str], + qualifiers: Optional[str], + ) -> None: + self.definition_name = "annotation" + + self.name = name + self.parameters = parameters + self.description = description + self.qualifiers = qualifiers + + +class MethodDef: + def __init__( + self, + name: str, + return_type: TypeName, + parameters: List[ParameterDef], + description: Optional[str], + qualifiers: Optional[str], + ) -> None: + self.definition_name = "method" + + self.name = name + self.return_type = return_type + self.parameters = parameters + self.description = description + self.qualifiers = qualifiers + + +class ConstantDef: + def __init__(self, name: str, value: str, text: Optional[str], bitfield: bool) -> None: + self.definition_name = "constant" + + self.name = name + self.value = value + self.text = text + self.is_bitfield = bitfield + + +class EnumDef: + def __init__(self, name: str, bitfield: bool) -> None: + self.definition_name = "enum" + + self.name = name + self.values: OrderedDict[str, ConstantDef] = OrderedDict() + self.is_bitfield = bitfield + + +class ThemeItemDef: + def __init__( + self, name: str, type_name: TypeName, data_name: str, text: Optional[str], default_value: Optional[str] + ) -> None: + self.definition_name = "theme item" + + self.name = name + self.type_name = type_name + self.data_name = data_name + self.text = text + self.default_value = default_value + + +class ClassDef: + def __init__(self, name: str) -> None: + self.definition_name = "class" + + self.name = name + self.constants: OrderedDict[str, ConstantDef] = OrderedDict() + self.enums: OrderedDict[str, EnumDef] = OrderedDict() + self.properties: OrderedDict[str, PropertyDef] = OrderedDict() + self.constructors: OrderedDict[str, List[MethodDef]] = OrderedDict() + self.methods: OrderedDict[str, List[MethodDef]] = OrderedDict() + self.operators: OrderedDict[str, List[MethodDef]] = OrderedDict() + self.signals: OrderedDict[str, SignalDef] = OrderedDict() + self.annotations: OrderedDict[str, List[AnnotationDef]] = OrderedDict() + self.theme_items: OrderedDict[str, ThemeItemDef] = OrderedDict() + self.inherits: Optional[str] = None + self.brief_description: Optional[str] = None + self.description: Optional[str] = None + self.tutorials: List[Tuple[str, str]] = [] + + # Used to match the class with XML source for output filtering purposes. + self.filepath: str = "" + + +def print_error(error: str, state: State) -> None: + print("{}{}ERROR:{} {}{}".format(STYLES["red"], STYLES["bold"], STYLES["regular"], error, STYLES["reset"])) + state.num_errors += 1 + + +def main() -> None: + # Enable ANSI escape code support on Windows 10 and later (for colored console output). + # <https://bugs.python.org/issue29059> + if platform.system().lower() == "windows": + from ctypes import windll, c_int, byref # type: ignore + + stdout_handle = windll.kernel32.GetStdHandle(c_int(-11)) + mode = c_int(0) + windll.kernel32.GetConsoleMode(c_int(stdout_handle), byref(mode)) + mode = c_int(mode.value | 4) + windll.kernel32.SetConsoleMode(c_int(stdout_handle), mode) + + parser = argparse.ArgumentParser() + parser.add_argument("path", nargs="+", help="A path to an XML file or a directory containing XML files to parse.") + parser.add_argument("--filter", default="", help="The filepath pattern for XML files to filter.") + parser.add_argument("--lang", "-l", default="en", help="Language to use for section headings.") + parser.add_argument( + "--color", + action="store_true", + help="If passed, force colored output even if stdout is not a TTY (useful for continuous integration).", + ) + 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() + + should_color = args.color or (hasattr(sys.stdout, "isatty") and sys.stdout.isatty()) + STYLES["red"] = "\x1b[91m" if should_color else "" + STYLES["green"] = "\x1b[92m" if should_color else "" + STYLES["bold"] = "\x1b[1m" if should_color else "" + STYLES["regular"] = "\x1b[22m" if should_color else "" + STYLES["reset"] = "\x1b[0m" if should_color else "" + + # Retrieve heading translations for the given language. + if not args.dry_run and args.lang != "en": + lang_file = os.path.join( + os.path.dirname(os.path.realpath(__file__)), "..", "translations", "{}.po".format(args.lang) + ) + if os.path.exists(lang_file): + try: + import polib + except ImportError: + print("Base template strings localization requires `polib`.") + exit(1) + + pofile = polib.pofile(lang_file) + for entry in pofile.translated_entries(): + if entry.msgid in BASE_STRINGS: + strings_l10n[entry.msgid] = entry.msgstr + else: + print('No PO file at "{}" for language "{}".'.format(lang_file, args.lang)) + + print("Checking for errors in the XML class reference...") + + file_list: List[str] = [] + + for path in args.path: + # Cut off trailing slashes so os.path.basename doesn't choke. + if path.endswith("/") or path.endswith("\\"): + 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: Dict[str, Tuple[ET.Element, str]] = {} + state = State() + + for cur_file in file_list: + try: + tree = ET.parse(cur_file) + except ET.ParseError as e: + print_error("{}: Parse error while reading the file: {}".format(cur_file, e), state) + continue + doc = tree.getroot() + + if "version" not in doc.attrib: + print_error('{}: "version" attribute missing from "doc".'.format(cur_file), state) + continue + + name = doc.attrib["name"] + if name in classes: + print_error('{}: Duplicate class "{}".'.format(cur_file, name), state) + continue + + classes[name] = (doc, cur_file) + + for name, data in classes.items(): + try: + state.parse_class(data[0], data[1]) + except Exception as e: + print_error("{}.xml: Exception while parsing class: {}".format(name, e), state) + + state.sort_classes() + + pattern = re.compile(args.filter) + + # Create the output folder recursively if it doesn't already exist. + os.makedirs(args.output, exist_ok=True) + + for class_name, class_def in state.classes.items(): + if args.filter and not pattern.search(class_def.filepath): + continue + state.current_class = class_name + make_rst_class(class_def, state, args.dry_run, args.output) + + if state.num_errors == 0: + print("{}No errors found in the class reference XML.{}".format(STYLES["green"], STYLES["reset"])) + if not args.dry_run: + print("Wrote reStructuredText files for each class to: %s" % args.output) + else: + if state.num_errors >= 2: + print( + "{}{} errors were found in the class reference XML. Please check the messages above.{}".format( + STYLES["red"], state.num_errors, STYLES["reset"] + ) + ) + else: + print( + "{}1 error was found in the class reference XML. Please check the messages above.{}".format( + STYLES["red"], STYLES["reset"] + ) + ) + exit(1) + + +def translate(string: str) -> str: + """Translate a string based on translations sourced from `doc/translations/*.po` + for a language if defined via the --lang command line argument. + Returns the original string if no translation exists. + """ + return strings_l10n.get(string, string) + + +def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: str) -> None: + class_name = class_def.name + + if dry_run: + f = open(os.devnull, "w", encoding="utf-8") + else: + f = open(os.path.join(output_dir, "class_" + class_name.lower() + ".rst"), "w", encoding="utf-8") + + # Remove the "Edit on Github" button from the online docs page. + f.write(":github_url: hide\n\n") + + # Warn contributors not to edit this file directly. + # Also provide links to the source files for reference. + + git_branch = "master" + if hasattr(version, "docs") and version.docs != "latest": + git_branch = version.docs + + source_xml_path = os.path.relpath(class_def.filepath, root_directory).replace("\\", "/") + source_github_url = "https://github.com/godotengine/godot/tree/{}/{}".format(git_branch, source_xml_path) + generator_github_url = "https://github.com/godotengine/godot/tree/{}/doc/tools/make_rst.py".format(git_branch) + + f.write(".. DO NOT EDIT THIS FILE!!!\n") + f.write(".. Generated automatically from Godot engine sources.\n") + f.write(".. Generator: " + generator_github_url + ".\n") + f.write(".. XML source: " + source_github_url + ".\n\n") + + # Document reference id and header. + f.write(".. _class_" + class_name + ":\n\n") + f.write(make_heading(class_name, "=", False)) + + # Inheritance tree + # Ascendants + if class_def.inherits: + inherits = class_def.inherits.strip() + f.write("**" + translate("Inherits:") + "** ") + first = True + while inherits in state.classes: + if not first: + f.write(" **<** ") + else: + first = False + + f.write(make_type(inherits, state)) + inode = state.classes[inherits].inherits + if inode: + inherits = inode.strip() + else: + break + f.write("\n\n") + + # Descendants + inherited: List[str] = [] + for c in state.classes.values(): + if c.inherits and c.inherits.strip() == class_name: + inherited.append(c.name) + + if len(inherited): + f.write("**" + translate("Inherited By:") + "** ") + for i, child in enumerate(inherited): + if i > 0: + f.write(", ") + f.write(make_type(child, state)) + f.write("\n\n") + + # Brief description + if class_def.brief_description is not None: + f.write(rstize_text(class_def.brief_description.strip(), class_def, state) + "\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(), class_def, state) + "\n\n") + + # Online tutorials + if len(class_def.tutorials) > 0: + f.write(make_heading("Tutorials", "-")) + for url, title in class_def.tutorials: + f.write("- " + make_link(url, title) + "\n\n") + + # Properties overview + if len(class_def.properties) > 0: + f.write(make_heading("Properties", "-")) + ml: List[Tuple[Optional[str], ...]] = [] + for property_def in class_def.properties.values(): + type_rst = property_def.type_name.to_rst(state) + default = property_def.default_value + if default is not None and property_def.overrides: + ref = ":ref:`{1}<class_{1}_property_{0}>`".format(property_def.name, property_def.overrides) + # Not using translate() for now as it breaks table formatting. + ml.append((type_rst, property_def.name, default + " " + "(overrides %s)" % ref)) + else: + ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name) + ml.append((type_rst, ref, default)) + format_table(f, ml, True) + + # Constructors, Methods, Operators overview + if len(class_def.constructors) > 0: + f.write(make_heading("Constructors", "-")) + ml: List[Tuple[Optional[str], ...]] = [] + for method_list in class_def.constructors.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, "constructor", state)) + format_table(f, ml) + + if len(class_def.methods) > 0: + f.write(make_heading("Methods", "-")) + ml: List[Tuple[Optional[str], ...]] = [] + for method_list in class_def.methods.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, "method", state)) + format_table(f, ml) + + if len(class_def.operators) > 0: + f.write(make_heading("Operators", "-")) + ml: List[Tuple[Optional[str], ...]] = [] + for method_list in class_def.operators.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, "operator", state)) + format_table(f, ml) + + # Theme properties + if len(class_def.theme_items) > 0: + f.write(make_heading("Theme Properties", "-")) + pl: List[Tuple[Optional[str], ...]] = [] + for theme_item_def in class_def.theme_items.values(): + ref = ":ref:`{0}<class_{2}_theme_{1}_{0}>`".format( + theme_item_def.name, theme_item_def.data_name, class_name + ) + pl.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) + format_table(f, pl, True) + + # Signals + if len(class_def.signals) > 0: + f.write(make_heading("Signals", "-")) + index = 0 + + for signal in class_def.signals.values(): + if index != 0: + f.write("----\n\n") + + f.write(".. _class_{}_signal_{}:\n\n".format(class_name, signal.name)) + _, signature = make_method_signature(class_def, signal, "", state) + f.write("- {}\n\n".format(signature)) + + if signal.description is not None and signal.description.strip() != "": + f.write(rstize_text(signal.description.strip(), signal, state) + "\n\n") + + index += 1 + + # Enums + if len(class_def.enums) > 0: + f.write(make_heading("Enumerations", "-")) + index = 0 + + for e in class_def.enums.values(): + if index != 0: + f.write("----\n\n") + + 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)) + + if e.is_bitfield: + f.write("flags **{}**:\n\n".format(e.name)) + else: + 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() != "": + # If value.text contains a bullet point list, each entry needs additional indentation + f.write(" --- " + indent_bullets(rstize_text(value.text.strip(), value, state))) + + f.write("\n\n") + + index += 1 + + # 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(), constant, state)) + + f.write("\n\n") + + # Annotations + if len(class_def.annotations) > 0: + f.write(make_heading("Annotations", "-")) + index = 0 + + for method_list in class_def.annotations.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write("----\n\n") + + if i == 0: + f.write(".. _class_{}_annotation_{}:\n\n".format(class_name, m.name.strip("@"))) + + _, signature = make_method_signature(class_def, m, "", state) + f.write("- {}\n\n".format(signature)) + + if m.description is not None and m.description.strip() != "": + f.write(rstize_text(m.description.strip(), m, state) + "\n\n") + + index += 1 + + # Property descriptions + if any(not p.overrides for p in class_def.properties.values()) > 0: + f.write(make_heading("Property Descriptions", "-")) + index = 0 + + for property_def in class_def.properties.values(): + if property_def.overrides: + continue + + if index != 0: + f.write("----\n\n") + + 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)) + + info: List[Tuple[Optional[str], ...]] = [] + # Not using translate() for now as it breaks table formatting. + if property_def.default_value is not None: + info.append(("*" + "Default" + "*", property_def.default_value)) + if property_def.setter is not None and not property_def.setter.startswith("_"): + info.append(("*" + "Setter" + "*", property_def.setter + "(" + "value" + ")")) + if property_def.getter is not None and not property_def.getter.startswith("_"): + info.append(("*" + "Getter" + "*", property_def.getter + "()")) + + if len(info) > 0: + format_table(f, info) + + if property_def.text is not None and property_def.text.strip() != "": + f.write(rstize_text(property_def.text.strip(), property_def, state) + "\n\n") + + index += 1 + + # Constructor, Method, Operator descriptions + if len(class_def.constructors) > 0: + f.write(make_heading("Constructor Descriptions", "-")) + index = 0 + + for method_list in class_def.constructors.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write("----\n\n") + + if i == 0: + f.write(".. _class_{}_constructor_{}:\n\n".format(class_name, m.name)) + + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write("- {} {}\n\n".format(ret_type, signature)) + + if m.description is not None and m.description.strip() != "": + f.write(rstize_text(m.description.strip(), m, state) + "\n\n") + + index += 1 + + if len(class_def.methods) > 0: + f.write(make_heading("Method Descriptions", "-")) + index = 0 + + for method_list in class_def.methods.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write("----\n\n") + + if i == 0: + f.write(".. _class_{}_method_{}:\n\n".format(class_name, m.name)) + + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write("- {} {}\n\n".format(ret_type, signature)) + + if m.description is not None and m.description.strip() != "": + f.write(rstize_text(m.description.strip(), m, state) + "\n\n") + + index += 1 + + if len(class_def.operators) > 0: + f.write(make_heading("Operator Descriptions", "-")) + index = 0 + + for method_list in class_def.operators.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write("----\n\n") + + if i == 0: + f.write( + ".. _class_{}_operator_{}_{}:\n\n".format( + class_name, sanitize_operator_name(m.name, state), m.return_type.type_name + ) + ) + + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write("- {} {}\n\n".format(ret_type, signature)) + + if m.description is not None and m.description.strip() != "": + f.write(rstize_text(m.description.strip(), m, state) + "\n\n") + + index += 1 + + # Theme property descriptions + if len(class_def.theme_items) > 0: + f.write(make_heading("Theme Property Descriptions", "-")) + index = 0 + + for theme_item_def in class_def.theme_items.values(): + if index != 0: + f.write("----\n\n") + + f.write(".. _class_{}_theme_{}_{}:\n\n".format(class_name, theme_item_def.data_name, theme_item_def.name)) + f.write("- {} **{}**\n\n".format(theme_item_def.type_name.to_rst(state), theme_item_def.name)) + + info = [] + if theme_item_def.default_value is not None: + # Not using translate() for now as it breaks table formatting. + info.append(("*" + "Default" + "*", theme_item_def.default_value)) + + if len(info) > 0: + format_table(f, info) + + if theme_item_def.text is not None and theme_item_def.text.strip() != "": + f.write(rstize_text(theme_item_def.text.strip(), theme_item_def, state) + "\n\n") + + index += 1 + + f.write(make_footer()) + + +def escape_rst(text: str, until_pos: int = -1) -> str: + # Escape \ character, otherwise it ends up as an escape character in rst + pos = 0 + while True: + pos = text.find("\\", pos, until_pos) + if pos == -1: + break + text = text[:pos] + "\\\\" + text[pos + 1 :] + pos += 2 + + # Escape * character to avoid interpreting it as emphasis + pos = 0 + while True: + pos = text.find("*", pos, until_pos) + if pos == -1: + break + text = text[:pos] + "\*" + text[pos + 1 :] + pos += 2 + + # Escape _ character at the end of a word to avoid interpreting it as an inline hyperlink + pos = 0 + while True: + pos = text.find("_", pos, until_pos) + if pos == -1: + break + if not text[pos + 1].isalnum(): # don't escape within a snake_case word + text = text[:pos] + "\_" + text[pos + 1 :] + pos += 2 + else: + pos += 1 + + return text + + +def format_codeblock(code_type: str, post_text: str, indent_level: int, state: State) -> Union[Tuple[str, int], None]: + end_pos = post_text.find("[/" + code_type + "]") + if end_pos == -1: + print_error("{}.xml: [" + code_type + "] without a closing tag.".format(state.current_class), state) + return None + + code_text = post_text[len("[" + code_type + "]") : end_pos] + post_text = post_text[end_pos:] + + # Remove extraneous tabs + code_pos = 0 + while True: + code_pos = code_text.find("\n", code_pos) + if code_pos == -1: + break + + to_skip = 0 + while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == "\t": + to_skip += 1 + + if to_skip > indent_level: + print_error( + "{}.xml: Four spaces should be used for indentation within [{}].".format( + state.current_class, code_type + ), + state, + ) + + if len(code_text[code_pos + to_skip + 1 :]) == 0: + code_text = code_text[:code_pos] + "\n" + code_pos += 1 + else: + code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1 :] + code_pos += 5 - to_skip + return ("\n[" + code_type + "]" + code_text + post_text, len("\n[" + code_type + "]" + code_text)) + + +def rstize_text( + text: str, + context: Union[ClassDef, SignalDef, ConstantDef, AnnotationDef, PropertyDef, MethodDef, ThemeItemDef, None], + state: State, +) -> str: + # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock" + pos = 0 + while True: + pos = text.find("\n", pos) + if pos == -1: + break + + pre_text = text[:pos] + indent_level = 0 + while pos + 1 < len(text) and text[pos + 1] == "\t": + pos += 1 + indent_level += 1 + post_text = text[pos + 1 :] + + # Handle codeblocks + if ( + post_text.startswith("[codeblock]") + or post_text.startswith("[gdscript]") + or post_text.startswith("[csharp]") + ): + block_type = post_text[1:].split("]")[0] + result = format_codeblock(block_type, post_text, indent_level, state) + if result is None: + return "" + text = pre_text + result[0] + pos += result[1] - indent_level + + # Handle normal text + else: + text = pre_text + "\n\n" + post_text + pos += 2 - indent_level + + next_brac_pos = text.find("[") + text = escape_rst(text, next_brac_pos) + + # Handle [tags] + inside_code = False + pos = 0 + tag_depth = 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] + + escape_pre = False + escape_post = False + + if tag_text in state.classes: + if tag_text == state.current_class: + # We don't want references to the same class + tag_text = "``{}``".format(tag_text) + else: + tag_text = make_type(tag_text, state) + escape_pre = True + escape_post = True + else: # command + cmd = tag_text + space_pos = tag_text.find(" ") + + if cmd == "/codeblock" or cmd == "/gdscript" or cmd == "/csharp": + 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: + param = tag_text[space_pos + 1 :] + tag_text = param + elif ( + cmd.startswith("method") + or cmd.startswith("member") + or cmd.startswith("signal") + or cmd.startswith("constant") + or cmd.startswith("theme_item") + ): + param = tag_text[space_pos + 1 :] + + if param.find(".") != -1: + ss = param.split(".") + if len(ss) > 2: + print_error('{}.xml: Bad reference: "{}".'.format(state.current_class, param), state) + class_param, method_param = ss + + else: + 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("constructor"): + if method_param not in class_def.constructors: + print_error( + '{}.xml: Unresolved constructor "{}".'.format(state.current_class, param), state + ) + ref_type = "_constructor" + + elif cmd.startswith("method"): + if method_param not in class_def.methods: + print_error('{}.xml: Unresolved method "{}".'.format(state.current_class, param), state) + ref_type = "_method" + + elif cmd.startswith("operator"): + if method_param not in class_def.operators: + print_error('{}.xml: Unresolved operator "{}".'.format(state.current_class, param), state) + ref_type = "_operator" + + elif cmd.startswith("member"): + if method_param not in class_def.properties: + print_error('{}.xml: Unresolved member "{}".'.format(state.current_class, param), state) + ref_type = "_property" + + elif cmd.startswith("theme_item"): + if method_param not in class_def.theme_items: + print_error('{}.xml: Unresolved theme item "{}".'.format(state.current_class, param), state) + ref_type = "_theme_{}".format(class_def.theme_items[method_param].data_name) + + elif cmd.startswith("signal"): + if method_param not in class_def.signals: + print_error('{}.xml: Unresolved signal "{}".'.format(state.current_class, param), state) + ref_type = "_signal" + + elif cmd.startswith("annotation"): + if method_param not in class_def.annotations: + print_error('{}.xml: Unresolved annotation "{}".'.format(state.current_class, param), state) + ref_type = "_annotation" + + elif cmd.startswith("constant"): + found = False + + # Search in the current class + search_class_defs = [class_def] + + if param.find(".") == -1: + # Also search in @GlobalScope as a last resort if no class was specified + search_class_defs.append(state.classes["@GlobalScope"]) + + for search_class_def in search_class_defs: + if method_param in search_class_def.constants: + class_param = search_class_def.name + found = True + + else: + for enum in search_class_def.enums.values(): + if method_param in enum.values: + class_param = search_class_def.name + found = True + break + + if not found: + print_error('{}.xml: Unresolved constant "{}".'.format(state.current_class, param), state) + ref_type = "_constant" + + else: + print_error( + '{}.xml: Unresolved type reference "{}" in method reference "{}".'.format( + state.current_class, class_param, param + ), + 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_pre = True + escape_post = True + elif cmd.startswith("param"): + param_name: str = "" + if space_pos >= 0: + param_name = tag_text[space_pos + 1 :].strip() + + if param_name == "": + context_name: str = "unknown context" + if context is not None: + context_name = '{} "{}" description'.format(context.definition_name, context.name) + + print_error( + "{}.xml: Empty argument reference in {}.".format(state.current_class, context_name), + state, + ) + else: + valid_context = ( + isinstance(context, MethodDef) + or isinstance(context, SignalDef) + or isinstance(context, AnnotationDef) + ) + if not valid_context: + context_name: str = "unknown context" + if context is not None: + context_name = '{} "{}" description'.format(context.definition_name, context.name) + + print_error( + '{}.xml: Argument reference "{}" used outside of method, signal, or annotation context in {}.'.format( + state.current_class, param_name, context_name + ), + state, + ) + else: + context_params: List[ParameterDef] = context.parameters + found = False + for param_def in context_params: + if param_def.name == param_name: + found = True + break + if not found: + print_error( + '{}.xml: Unresolved argument reference "{}" in {} "{}" description.'.format( + state.current_class, param_name, context.definition_name, context.name + ), + state, + ) + + if param_name == "": + tag_text = "" + else: + tag_text = "``{}``".format(param_name) + elif cmd.find("image=") == 0: + tag_text = "" # '' + elif cmd.find("url=") == 0: + # URLs are handled in full here as we need to extract the optional link + # title to use `make_link`. + link_url = cmd[4:] + endurl_pos = text.find("[/url]", endq_pos + 1) + if endurl_pos == -1: + print_error( + "{}.xml: Tag depth mismatch for [url]: no closing [/url]".format(state.current_class), state + ) + break + link_title = text[endq_pos + 1 : endurl_pos] + tag_text = make_link(link_url, link_title) + + pre_text = text[:pos] + post_text = text[endurl_pos + 6 :] + + if pre_text and pre_text[-1] not in MARKUP_ALLOWED_PRECEDENT: + pre_text += "\ " + if post_text and post_text[0] not in MARKUP_ALLOWED_SUBSEQUENT: + post_text = "\ " + post_text + + text = pre_text + tag_text + post_text + pos = len(pre_text) + len(tag_text) + continue + 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 == "gdscript": + tag_depth += 1 + tag_text = "\n .. code-tab:: gdscript\n" + inside_code = True + elif cmd == "csharp": + tag_depth += 1 + tag_text = "\n .. code-tab:: csharp\n" + inside_code = True + elif cmd == "codeblocks": + tag_depth += 1 + tag_text = "\n.. tabs::" + elif cmd == "/codeblocks": + tag_depth -= 1 + tag_text = "" + elif cmd == "br": + # Make a new paragraph instead of a linebreak, rst is not so linebreak friendly + tag_text = "\n\n" + # Strip potential leading spaces + while post_text[0] == " ": + post_text = post_text[1:] + elif cmd == "i" or cmd == "/i": + if cmd == "/i": + tag_depth -= 1 + escape_post = True + else: + tag_depth += 1 + escape_pre = True + tag_text = "*" + elif cmd == "b" or cmd == "/b": + if cmd == "/b": + tag_depth -= 1 + escape_post = True + else: + tag_depth += 1 + escape_pre = True + tag_text = "**" + elif cmd == "u" or cmd == "/u": + if cmd == "/u": + tag_depth -= 1 + escape_post = True + else: + tag_depth += 1 + escape_pre = True + tag_text = "" + elif cmd == "code": + tag_text = "``" + tag_depth += 1 + inside_code = True + escape_pre = True + elif cmd == "kbd": + tag_text = ":kbd:`" + tag_depth += 1 + escape_pre = True + elif cmd == "/kbd": + tag_text = "`" + tag_depth -= 1 + escape_post = True + elif cmd.startswith("enum "): + tag_text = make_enum(cmd[5:], state) + escape_pre = True + escape_post = True + else: + tag_text = make_type(tag_text, state) + escape_pre = True + escape_post = True + + # Properly escape things like `[Node]s` + if escape_pre and pre_text and pre_text[-1] not in MARKUP_ALLOWED_PRECEDENT: + pre_text += "\ " + if escape_post and post_text and post_text[0] not in MARKUP_ALLOWED_SUBSEQUENT: + 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) + + if tag_depth > 0: + print_error( + "{}.xml: Tag depth mismatch: too many (or too little) open/close tags.".format(state.current_class), state + ) + + return text + + +def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_columns: bool = False) -> None: + if len(data) == 0: + return + + column_sizes = [0] * len(data[0]) + for row in data: + for i, text in enumerate(row): + text_length = len(text or "") + if text_length > column_sizes[i]: + column_sizes[i] = text_length + + sep = "" + for size in column_sizes: + if size == 0 and remove_empty_columns: + continue + sep += "+" + "-" * (size + 2) + sep += "+\n" + f.write(sep) + + for row in data: + row_text = "|" + for i, text in enumerate(row): + if column_sizes[i] == 0 and remove_empty_columns: + continue + row_text += " " + (text or "").ljust(column_sizes[i]) + " |" + row_text += "\n" + f.write(row_text) + f.write(sep) + f.write("\n") + + +def make_type(klass: str, state: State) -> str: + if klass.find("*") != -1: # Pointer, ignore + return klass + link_type = klass + if link_type.endswith("[]"): # Typed array, strip [] to link to contained type. + link_type = link_type[:-2] + if link_type in state.classes: + return ":ref:`{}<class_{}>`".format(klass, link_type) + print_error('{}.xml: Unresolved type "{}".'.format(state.current_class, klass), state) + return klass + + +def make_enum(t: str, state: State) -> str: + p = t.find(".") + if p >= 0: + c = t[0:p] + e = t[p + 1 :] + # Variant enums live in GlobalScope but still use periods. + if c == "Variant": + c = "@GlobalScope" + e = "Variant." + e + else: + c = state.current_class + e = 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) + + # Don't fail for `Vector3.Axis`, as this enum is a special case which is expected not to be resolved. + if "{}.{}".format(c, e) != "Vector3.Axis": + print_error('{}.xml: Unresolved enum "{}".'.format(state.current_class, t), state) + + return t + + +def make_method_signature( + class_def: ClassDef, definition: Union[AnnotationDef, MethodDef, SignalDef], ref_type: str, state: State +) -> Tuple[str, str]: + ret_type = "" + + is_method_def = isinstance(definition, MethodDef) + if is_method_def: + ret_type = definition.return_type.to_rst(state) + + qualifiers = None + if is_method_def or isinstance(definition, AnnotationDef): + qualifiers = definition.qualifiers + + out = "" + + if is_method_def and ref_type != "": + if ref_type == "operator": + out += ":ref:`{0}<class_{1}_{2}_{3}_{4}>` ".format( + definition.name.replace("<", "\\<"), # So operator "<" gets correctly displayed. + class_def.name, + ref_type, + sanitize_operator_name(definition.name, state), + definition.return_type.type_name, + ) + else: + out += ":ref:`{0}<class_{1}_{2}_{0}>` ".format(definition.name, class_def.name, ref_type) + else: + out += "**{}** ".format(definition.name) + + out += "**(**" + for i, arg in enumerate(definition.parameters): + if i > 0: + out += ", " + else: + out += " " + + out += "{} {}".format(arg.type_name.to_rst(state), arg.name) + + if arg.default_value is not None: + out += "=" + arg.default_value + + if qualifiers is not None and "vararg" in qualifiers: + if len(definition.parameters) > 0: + out += ", ..." + else: + out += " ..." + + out += " **)**" + + if qualifiers is not None: + # Use substitutions for abbreviations. This is used to display tooltips on hover. + # See `make_footer()` for descriptions. + for qualifier in qualifiers.split(): + out += " |" + qualifier + "|" + + return ret_type, out + + +def make_heading(title: str, underline: str, l10n: bool = True) -> str: + if l10n: + new_title = translate(title) + if new_title != title: + title = new_title + underline *= 2 # Double length to handle wide chars. + return title + "\n" + (underline * len(title)) + "\n\n" + + +def make_footer() -> str: + # Generate reusable abbreviation substitutions. + # This way, we avoid bloating the generated rST with duplicate abbreviations. + # fmt: off + return ( + ".. |virtual| replace:: :abbr:`virtual (" + translate("This method should typically be overridden by the user to have any effect.") + ")`\n" + ".. |const| replace:: :abbr:`const (" + translate("This method has no side effects. It doesn't modify any of the instance's member variables.") + ")`\n" + ".. |vararg| replace:: :abbr:`vararg (" + translate("This method accepts any number of arguments after the ones described here.") + ")`\n" + ".. |constructor| replace:: :abbr:`constructor (" + translate("This method is used to construct a type.") + ")`\n" + ".. |static| replace:: :abbr:`static (" + translate("This method doesn't need an instance to be called, so it can be called directly using the class name.") + ")`\n" + ".. |operator| replace:: :abbr:`operator (" + translate("This method describes a valid operator to use with this type as left-hand operand.") + ")`\n" + ) + # fmt: on + + +def make_link(url: str, title: str) -> str: + match = GODOT_DOCS_PATTERN.search(url) + 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` + # Or use the title if provided. + if title != "": + return "`" + title + " <../" + groups[0] + ".html" + groups[1] + ">`__" + return "`" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`__ in :doc:`../" + groups[0] + "`" + elif match.lastindex == 1: + # Doc reference, for example: + # `Math` + if title != "": + return ":doc:`" + title + " <../" + groups[0] + ">`" + return ":doc:`../" + groups[0] + "`" + + # External link, for example: + # `http://enet.bespin.org/usergroup0.html` + if title != "": + return "`" + title + " <" + url + ">`__" + return "`" + url + " <" + url + ">`__" + + +def sanitize_operator_name(dirty_name: str, state: State) -> str: + clear_name = dirty_name.replace("operator ", "") + + if clear_name == "!=": + clear_name = "neq" + elif clear_name == "==": + clear_name = "eq" + + elif clear_name == "<": + clear_name = "lt" + elif clear_name == "<=": + clear_name = "lte" + elif clear_name == ">": + clear_name = "gt" + elif clear_name == ">=": + clear_name = "gte" + + elif clear_name == "+": + clear_name = "sum" + elif clear_name == "-": + clear_name = "dif" + elif clear_name == "*": + clear_name = "mul" + elif clear_name == "/": + clear_name = "div" + elif clear_name == "%": + clear_name = "mod" + elif clear_name == "**": + clear_name = "pow" + + elif clear_name == "unary+": + clear_name = "unplus" + elif clear_name == "unary-": + clear_name = "unminus" + + elif clear_name == "<<": + clear_name = "bwsl" + elif clear_name == ">>": + clear_name = "bwsr" + elif clear_name == "&": + clear_name = "bwand" + elif clear_name == "|": + clear_name = "bwor" + elif clear_name == "^": + clear_name = "bwxor" + elif clear_name == "~": + clear_name = "bwnot" + + elif clear_name == "[]": + clear_name = "idx" + + else: + clear_name = "xxx" + print_error('Unsupported operator type "{}", please add the missing rule.'.format(dirty_name), state) + + return clear_name + + +def indent_bullets(text: str) -> str: + # Take the text and check each line for a bullet point represented by "-". + # Where found, indent the given line by a further "\t". + # Used to properly indent bullet points contained in the description for enum values. + # Ignore the first line - text will be prepended to it so bullet points wouldn't work anyway. + bullet_points = "-" + + lines = text.splitlines(keepends=True) + for line_index, line in enumerate(lines[1:], start=1): + pos = 0 + while pos < len(line) and line[pos] == "\t": + pos += 1 + + if pos < len(line) and line[pos] in bullet_points: + lines[line_index] = line[:pos] + "\t" + line[pos:] + + return "".join(lines) + + +if __name__ == "__main__": + main() diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py deleted file mode 100755 index a23324fd24..0000000000 --- a/doc/tools/makerst.py +++ /dev/null @@ -1,1135 +0,0 @@ -#!/usr/bin/env python3 - -import argparse -import os -import re -import xml.etree.ElementTree as ET -from collections import OrderedDict - -# 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( - r"^http(?:s)?://docs\.godotengine\.org/(?:[a-zA-Z0-9.\-_]*)/(?:[a-zA-Z0-9.\-_]*)/(.*)\.html(#.*)?$" -) - - -def print_error(error, state): # type: (str, State) -> None - print("ERROR: {}".format(error)) - state.errored = True - - -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, default_value, overridden - ): # type: (str, TypeName, Optional[str], Optional[str], Optional[str], Optional[str], Optional[bool]) -> None - self.name = name - self.type_name = type_name - self.setter = setter - self.getter = getter - self.text = text - self.default_value = default_value - self.overridden = overridden - - -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, data_name, text, default_value - ): # type: (str, TypeName, str, Optional[str], Optional[str]) -> None - self.name = name - self.type_name = type_name - self.data_name = data_name - self.text = text - self.default_value = default_value - - -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.theme_items = OrderedDict() # type: OrderedDict[str, ThemeItemDef] - self.inherits = None # type: Optional[str] - self.brief_description = None # type: Optional[str] - self.description = None # type: Optional[str] - self.tutorials = [] # type: List[Tuple[str, str]] - - # Used to match the class with XML source for output filtering purposes. - self.filepath = "" # type: 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, filepath): # type: (ET.Element, str) -> None - class_name = class_root.attrib["name"] - - class_def = ClassDef(class_name) - self.classes[class_name] = class_def - class_def.filepath = filepath - - inherits = class_root.get("inherits") - if inherits is not None: - class_def.inherits = inherits - - 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 - default_value = property.get("default") or None - if default_value is not None: - default_value = "``{}``".format(default_value) - overridden = property.get("override") or False - - property_def = PropertyDef( - property_name, type_name, setter, getter, property.text, default_value, overridden - ) - 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 - - params = parse_arguments(signal) - - desc_element = signal.find("description") - signal_desc = None - if desc_element is not None: - signal_desc = desc_element.text - - 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: - for theme_item in theme_items: - assert theme_item.tag == "theme_item" - - theme_item_name = theme_item.attrib["name"] - theme_item_data_name = theme_item.attrib["data_type"] - theme_item_id = "{}_{}".format(theme_item_data_name, theme_item_name) - if theme_item_id in class_def.theme_items: - print_error( - "Duplicate theme property '{}' of type '{}', file: {}".format( - theme_item_name, theme_item_data_name, class_name - ), - self, - ) - continue - - default_value = theme_item.get("default") or None - if default_value is not None: - default_value = "``{}``".format(default_value) - - theme_item_def = ThemeItemDef( - theme_item_name, - TypeName.from_element(theme_item), - theme_item_data_name, - theme_item.text, - default_value, - ) - class_def.theme_items[theme_item_id] = 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.strip(), link.get("title", ""))) - - 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.") - parser.add_argument("--filter", default="", help="The filepath pattern for XML files to filter.") - 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() - - print("Checking for errors in the XML class reference...") - - 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 - - name = doc.attrib["name"] - if name in classes: - print_error("Duplicate class '{}'".format(name), state) - continue - - classes[name] = (doc, cur_file) - - for name, data in classes.items(): - try: - state.parse_class(data[0], data[1]) - except Exception as e: - print_error("Exception while parsing class '{}': {}".format(name, e), state) - - state.sort_classes() - - pattern = re.compile(args.filter) - - # Create the output folder recursively if it doesn't already exist. - os.makedirs(args.output, exist_ok=True) - - for class_name, class_def in state.classes.items(): - if args.filter and not pattern.search(class_def.filepath): - continue - state.current_class = class_name - make_rst_class(class_def, state, args.dry_run, args.output) - - if not state.errored: - print("No errors found.") - if not args.dry_run: - print("Wrote reStructuredText files for each class to: %s" % args.output) - else: - print("Errors were found in the class reference XML. Please check the messages above.") - 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", encoding="utf-8") - 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(":github_url: hide\n\n") - 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") - - # Brief description - if class_def.brief_description is not None: - f.write(rstize_text(class_def.brief_description.strip(), state) + "\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 url, title in class_def.tutorials: - f.write("- " + make_link(url, title) + "\n\n") - - # Properties overview - if len(class_def.properties) > 0: - f.write(make_heading("Properties", "-")) - ml = [] # type: List[Tuple[str, str, str]] - for property_def in class_def.properties.values(): - type_rst = property_def.type_name.to_rst(state) - default = property_def.default_value - if default is not None and property_def.overridden: - ml.append((type_rst, property_def.name, default + " *(parent override)*")) - else: - ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name) - ml.append((type_rst, ref, default)) - format_table(f, ml, True) - - # 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 len(class_def.theme_items) > 0: - f.write(make_heading("Theme Properties", "-")) - pl = [] - for theme_item_def in class_def.theme_items.values(): - ref = ":ref:`{0}<class_{2}_theme_{1}_{0}>`".format( - theme_item_def.name, theme_item_def.data_name, class_name - ) - pl.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) - format_table(f, pl, True) - - # Signals - if len(class_def.signals) > 0: - f.write(make_heading("Signals", "-")) - index = 0 - - for signal in class_def.signals.values(): - if index != 0: - f.write("----\n\n") - - 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 not None and signal.description.strip() != "": - f.write(rstize_text(signal.description.strip(), state) + "\n\n") - - index += 1 - - # Enums - if len(class_def.enums) > 0: - f.write(make_heading("Enumerations", "-")) - index = 0 - - for e in class_def.enums.values(): - if index != 0: - f.write("----\n\n") - - 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") - - index += 1 - - # 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") - - # Property descriptions - if any(not p.overridden for p in class_def.properties.values()) > 0: - f.write(make_heading("Property Descriptions", "-")) - index = 0 - - for property_def in class_def.properties.values(): - if property_def.overridden: - continue - - if index != 0: - f.write("----\n\n") - - 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)) - - info = [] - if property_def.default_value is not None: - info.append(("*Default*", property_def.default_value)) - if property_def.setter is not None and not property_def.setter.startswith("_"): - info.append(("*Setter*", property_def.setter + "(value)")) - if property_def.getter is not None and not property_def.getter.startswith("_"): - info.append(("*Getter*", property_def.getter + "()")) - - if len(info) > 0: - format_table(f, info) - - if property_def.text is not None and property_def.text.strip() != "": - f.write(rstize_text(property_def.text.strip(), state) + "\n\n") - - index += 1 - - # Method descriptions - if len(class_def.methods) > 0: - f.write(make_heading("Method Descriptions", "-")) - index = 0 - - for method_list in class_def.methods.values(): - for i, m in enumerate(method_list): - if index != 0: - f.write("----\n\n") - - if i == 0: - 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 not None and m.description.strip() != "": - f.write(rstize_text(m.description.strip(), state) + "\n\n") - - index += 1 - - # Theme property descriptions - if len(class_def.theme_items) > 0: - f.write(make_heading("Theme Property Descriptions", "-")) - index = 0 - - for theme_item_def in class_def.theme_items.values(): - if index != 0: - f.write("----\n\n") - - f.write(".. _class_{}_theme_{}_{}:\n\n".format(class_name, theme_item_def.data_name, theme_item_def.name)) - f.write("- {} **{}**\n\n".format(theme_item_def.type_name.to_rst(state), theme_item_def.name)) - - info = [] - if theme_item_def.default_value is not None: - info.append(("*Default*", theme_item_def.default_value)) - - if len(info) > 0: - format_table(f, info) - - if theme_item_def.text is not None and theme_item_def.text.strip() != "": - f.write(rstize_text(theme_item_def.text.strip(), state) + "\n\n") - - index += 1 - - f.write(make_footer()) - - -def escape_rst(text, until_pos=-1): # type: (str) -> str - # Escape \ character, otherwise it ends up as an escape character in rst - pos = 0 - while True: - pos = text.find("\\", pos, until_pos) - if pos == -1: - break - text = text[:pos] + "\\\\" + text[pos + 1 :] - pos += 2 - - # Escape * character to avoid interpreting it as emphasis - pos = 0 - while True: - pos = text.find("*", pos, until_pos) - if pos == -1: - break - text = text[:pos] + "\*" + text[pos + 1 :] - pos += 2 - - # Escape _ character at the end of a word to avoid interpreting it as an inline hyperlink - pos = 0 - while True: - pos = text.find("_", pos, until_pos) - if pos == -1: - break - if not text[pos + 1].isalnum(): # don't escape within a snake_case word - text = text[:pos] + "\_" + text[pos + 1 :] - pos += 2 - else: - pos += 1 - - return text - - -def format_codeblock(code_type, post_text, indent_level, state): # types: str, str, int, state - end_pos = post_text.find("[/" + code_type + "]") - if end_pos == -1: - print_error("[" + code_type + "] without a closing tag, file: {}".format(state.current_class), state) - return None - - code_text = post_text[len("[" + code_type + "]") : end_pos] - post_text = post_text[end_pos:] - - # Remove extraneous tabs - code_pos = 0 - while True: - code_pos = code_text.find("\n", code_pos) - if code_pos == -1: - break - - to_skip = 0 - while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == "\t": - to_skip += 1 - - if to_skip > indent_level: - print_error( - "Four spaces should be used for indentation within [" - + code_type - + "], file: {}".format(state.current_class), - state, - ) - - if len(code_text[code_pos + to_skip + 1 :]) == 0: - code_text = code_text[:code_pos] + "\n" - code_pos += 1 - else: - code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1 :] - code_pos += 5 - to_skip - return ["\n[" + code_type + "]" + code_text + post_text, len("\n[" + code_type + "]" + code_text)] - - -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: - pos = text.find("\n", pos) - if pos == -1: - break - - pre_text = text[:pos] - indent_level = 0 - while text[pos + 1] == "\t": - pos += 1 - indent_level += 1 - post_text = text[pos + 1 :] - - # Handle codeblocks - if ( - post_text.startswith("[codeblock]") - or post_text.startswith("[gdscript]") - or post_text.startswith("[csharp]") - ): - block_type = post_text[1:].split("]")[0] - result = format_codeblock(block_type, post_text, indent_level, state) - if result is None: - return "" - text = pre_text + result[0] - pos += result[1] - - # Handle normal text - else: - text = pre_text + "\n\n" + post_text - pos += 2 - - next_brac_pos = text.find("[") - text = escape_rst(text, next_brac_pos) - - # Handle [tags] - inside_code = False - inside_url = False - url_has_name = False - url_link = "" - pos = 0 - tag_depth = 0 - previous_pos = 0 - while True: - pos = text.find("[", pos) - if inside_url and (pos > previous_pos): - url_has_name = True - 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] - - escape_post = False - - if tag_text in state.classes: - if tag_text == state.current_class: - # We don't want references to the same class - tag_text = "``{}``".format(tag_text) - else: - tag_text = make_type(tag_text, state) - escape_post = True - else: # command - cmd = tag_text - space_pos = tag_text.find(" ") - if cmd == "/codeblock" or cmd == "/gdscript" or cmd == "/csharp": - 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: - param = tag_text[space_pos + 1 :] - tag_text = param - 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: - print_error("Bad reference: '{}', file: {}".format(param, state.current_class), state) - class_param, method_param = ss - - else: - 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 - - # Search in the current class - search_class_defs = [class_def] - - if param.find(".") == -1: - # Also search in @GlobalScope as a last resort if no class was specified - search_class_defs.append(state.classes["@GlobalScope"]) - - for search_class_def in search_class_defs: - if method_param in search_class_def.constants: - class_param = search_class_def.name - found = True - - else: - for enum in search_class_def.enums.values(): - if method_param in enum.values: - class_param = search_class_def.name - 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: - url_link = cmd[4:] - tag_text = "`" - tag_depth += 1 - inside_url = True - url_has_name = False - elif cmd == "/url": - tag_text = ("" if url_has_name else url_link) + " <" + url_link + ">`_" - tag_depth -= 1 - escape_post = True - inside_url = False - url_has_name = False - 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 == "gdscript": - tag_depth += 1 - tag_text = "\n .. code-tab:: gdscript\n" - inside_code = True - elif cmd == "csharp": - tag_depth += 1 - tag_text = "\n .. code-tab:: csharp\n" - inside_code = True - elif cmd == "codeblocks": - tag_depth += 1 - tag_text = "\n.. tabs::" - elif cmd == "/codeblocks": - tag_depth -= 1 - tag_text = "" - elif cmd == "br": - # Make a new paragraph instead of a linebreak, rst is not so linebreak friendly - tag_text = "\n\n" - # Strip potential leading spaces - 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 == "kbd": - tag_text = ":kbd:`" - tag_depth += 1 - elif cmd == "/kbd": - tag_text = "`" - tag_depth -= 1 - elif cmd.startswith("enum "): - tag_text = make_enum(cmd[5:], state) - escape_post = True - else: - 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() or post_text[0] == "("): # 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) - previous_pos = pos - - if tag_depth > 0: - print_error("Tag depth mismatch: too many/little open/close tags, file: {}".format(state.current_class), state) - - return text - - -def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterable[Tuple[str, ...]]) -> None - if len(data) == 0: - return - - column_sizes = [0] * len(data[0]) - for row in data: - for i, text in enumerate(row): - text_length = len(text or "") - if text_length > column_sizes[i]: - column_sizes[i] = text_length - - sep = "" - for size in column_sizes: - if size == 0 and remove_empty_columns: - continue - sep += "+" + "-" * (size + 2) - sep += "+\n" - f.write(sep) - - for row in data: - row_text = "|" - for i, text in enumerate(row): - if column_sizes[i] == 0 and remove_empty_columns: - continue - row_text += " " + (text or "").ljust(column_sizes[i]) + " |" - row_text += "\n" - f.write(row_text) - f.write(sep) - f.write("\n") - - -def make_type(klass, state): # type: (str, State) -> str - if klass.find("*") != -1: # Pointer, ignore - return klass - link_type = klass - if link_type.endswith("[]"): # Typed array, strip [] to link to contained type. - link_type = link_type[:-2] - if link_type in state.classes: - return ":ref:`{}<class_{}>`".format(klass, link_type) - print_error("Unresolved type '{}', file: {}".format(klass, state.current_class), state) - return klass - - -def make_enum(t, state): # type: (str, State) -> str - p = t.find(".") - if p >= 0: - c = t[0:p] - e = t[p + 1 :] - # Variant enums live in GlobalScope but still use periods. - if c == "Variant": - c = "@GlobalScope" - e = "Variant." + e - else: - c = state.current_class - e = 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) - - # Don't fail for `Vector3.Axis`, as this enum is a special case which is expected not to be resolved. - if "{}.{}".format(c, e) != "Vector3.Axis": - print_error("Unresolved enum '{}', file: {}".format(t, state.current_class), state) - - return t - - -def make_method_signature( - class_def, method_def, make_ref, state -): # type: (ClassDef, Union[MethodDef, SignalDef], bool, State) -> Tuple[str, str] - ret_type = " " - - ref_type = "signal" - if isinstance(method_def, MethodDef): - ret_type = method_def.return_type.to_rst(state) - ref_type = "method" - - out = "" - - if make_ref: - out += ":ref:`{0}<class_{1}_{2}_{0}>` ".format(method_def.name, class_def.name, ref_type) - else: - out += "**{}** ".format(method_def.name) - - out += "**(**" - for i, arg in enumerate(method_def.parameters): - if i > 0: - out += ", " - else: - out += " " - - out += "{} {}".format(arg.type_name.to_rst(state), arg.name) - - if arg.default_value is not None: - out += "=" + arg.default_value - - 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: - out += " ..." - - out += " **)**" - - if isinstance(method_def, MethodDef) and method_def.qualifiers is not None: - # Use substitutions for abbreviations. This is used to display tooltips on hover. - # See `make_footer()` for descriptions. - for qualifier in method_def.qualifiers.split(): - out += " |" + qualifier + "|" - - return ret_type, out - - -def make_heading(title, underline): # type: (str, str) -> str - return title + "\n" + (underline * len(title)) + "\n\n" - - -def make_footer(): # type: () -> str - # Generate reusable abbreviation substitutions. - # This way, we avoid bloating the generated rST with duplicate abbreviations. - # fmt: off - return ( - ".. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`\n" - ".. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`\n" - ".. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`\n" - ".. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`\n" - ".. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`\n" - ) - # fmt: on - - -def make_link(url, title): # type: (str, str) -> str - match = GODOT_DOCS_PATTERN.search(url) - 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` - return "`" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`" - # Commented out alternative: Instead just emit: - # `Subsection in Exporting For Web` - # return "`Subsection <../" + groups[0] + ".html" + groups[1] + ">`__ in :doc:`../" + groups[0] + "`" - elif match.lastindex == 1: - # Doc reference, for example: - # `Math` - return ":doc:`../" + groups[0] + "`" - else: - # External link, for example: - # `http://enet.bespin.org/usergroup0.html` - if title != "": - return "`" + title + " <" + url + ">`_" - else: - return "`" + url + " <" + url + ">`_" - - -if __name__ == "__main__": - main() |