diff options
Diffstat (limited to 'doc/tools/make_rst.py')
| -rwxr-xr-x | doc/tools/make_rst.py | 1365 |
1 files changed, 827 insertions, 538 deletions
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 469bb4a310..519554e026 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -9,15 +9,13 @@ 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 -# 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 - # $DOCS_URL/path/to/page.html(#fragment-tag) GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$") @@ -61,127 +59,21 @@ BASE_STRINGS = [ "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 = {} - -STYLES = {} - - -def print_error(error, state): # type: (str, State) -> None - print("{}{}ERROR:{} {}{}".format(STYLES["red"], STYLES["bold"], STYLES["regular"], error, STYLES["reset"])) - state.num_errors += 1 - - -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, overrides - ): # type: (str, TypeName, Optional[str], Optional[str], Optional[str], Optional[str], Optional[str]) -> None - 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, 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 +strings_l10n: Dict[str, str] = {} - -class ConstantDef: - def __init__(self, name, value, text, bitfield): # type: (str, str, Optional[str], Optional[bool]) -> None - self.name = name - self.value = value - self.text = text - self.is_bitfield = bitfield - - -class EnumDef: - def __init__(self, name, bitfield): # type: (str, Optional[bool]) -> None - self.name = name - self.values = OrderedDict() # type: OrderedDict[str, ConstantDef] - self.is_bitfield = bitfield - - -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.constructors = OrderedDict() # type: OrderedDict[str, List[MethodDef]] - self.methods = OrderedDict() # type: OrderedDict[str, List[MethodDef]] - self.operators = OrderedDict() # type: OrderedDict[str, List[MethodDef]] - self.signals = OrderedDict() # type: OrderedDict[str, SignalDef] - self.annotations = OrderedDict() # type: OrderedDict[str, List[MethodDef]] - 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 +STYLES: Dict[str, str] = {} class State: - def __init__(self): # type: () -> None + def __init__(self) -> None: self.num_errors = 0 - self.classes = OrderedDict() # type: OrderedDict[str, ClassDef] - self.current_class = "" # type: str + self.num_warnings = 0 + self.classes: OrderedDict[str, ClassDef] = OrderedDict() + self.current_class: str = "" - def parse_class(self, class_root, filepath): # type: (ET.Element, str) -> None + 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 @@ -233,11 +125,10 @@ class State: return_element = constructor.find("return") if return_element is not None: return_type = TypeName.from_element(return_element) - else: return_type = TypeName("void") - params = parse_arguments(constructor) + params = self.parse_params(constructor, "constructor") desc_element = constructor.find("description") method_desc = None @@ -245,6 +136,7 @@ class State: 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] = [] @@ -265,7 +157,7 @@ class State: else: return_type = TypeName("void") - params = parse_arguments(method) + params = self.parse_params(method, "method") desc_element = method.find("description") method_desc = None @@ -293,7 +185,7 @@ class State: else: return_type = TypeName("void") - params = parse_arguments(operator) + params = self.parse_params(operator, "operator") desc_element = operator.find("description") method_desc = None @@ -301,6 +193,7 @@ class State: 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] = [] @@ -314,7 +207,7 @@ class State: constant_name = constant.attrib["name"] value = constant.attrib["value"] enum = constant.get("enum") - is_bitfield = constant.get("is_bitfield") or False + 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: @@ -341,14 +234,14 @@ class State: annotation_name = annotation.attrib["name"] qualifiers = annotation.get("qualifiers") - params = parse_arguments(annotation) + 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 = MethodDef(annotation_name, return_type, params, annotation_desc, qualifiers) + annotation_def = AnnotationDef(annotation_name, params, annotation_desc, qualifiers) if annotation_name not in class_def.annotations: class_def.annotations[annotation_name] = [] @@ -365,7 +258,7 @@ class State: print_error('{}.xml: Duplicate signal "{}".'.format(class_name, signal_name), self) continue - params = parse_arguments(signal) + params = self.parse_params(signal, "signal") desc_element = signal.find("description") signal_desc = None @@ -413,31 +306,190 @@ class State: if link.text is not None: class_def.tutorials.append((link.text.strip(), link.get("title", ""))) - def sort_classes(self): # type: () -> None + 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])) -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") +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 DefinitionBase: + def __init__( + self, + definition_name: str, + name: str, + ) -> None: + self.definition_name = definition_name + self.name = name + + +class PropertyDef(DefinitionBase): + 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: + super().__init__("property", 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(DefinitionBase): + def __init__(self, name: str, type_name: TypeName, default_value: Optional[str]) -> None: + super().__init__("parameter", name) + + self.type_name = type_name + self.default_value = default_value + + +class SignalDef(DefinitionBase): + def __init__(self, name: str, parameters: List[ParameterDef], description: Optional[str]) -> None: + super().__init__("signal", name) + + self.parameters = parameters + self.description = description + + +class AnnotationDef(DefinitionBase): + def __init__( + self, + name: str, + parameters: List[ParameterDef], + description: Optional[str], + qualifiers: Optional[str], + ) -> None: + super().__init__("annotation", name) + + self.parameters = parameters + self.description = description + self.qualifiers = qualifiers + + +class MethodDef(DefinitionBase): + def __init__( + self, + name: str, + return_type: TypeName, + parameters: List[ParameterDef], + description: Optional[str], + qualifiers: Optional[str], + ) -> None: + super().__init__("method", name) + + self.return_type = return_type + self.parameters = parameters + self.description = description + self.qualifiers = qualifiers + - params[index] = ParameterDef(param_name, type_name, default) +class ConstantDef(DefinitionBase): + def __init__(self, name: str, value: str, text: Optional[str], bitfield: bool) -> None: + super().__init__("constant", name) - cast = params # type: List[ParameterDef] + self.value = value + self.text = text + self.is_bitfield = bitfield - return cast +class EnumDef(DefinitionBase): + def __init__(self, name: str, bitfield: bool) -> None: + super().__init__("enum", name) -def main(): # type: () -> None + self.values: OrderedDict[str, ConstantDef] = OrderedDict() + self.is_bitfield = bitfield + + +class ThemeItemDef(DefinitionBase): + def __init__( + self, name: str, type_name: TypeName, data_name: str, text: Optional[str], default_value: Optional[str] + ) -> None: + super().__init__("theme item", name) + + self.type_name = type_name + self.data_name = data_name + self.text = text + self.default_value = default_value + + +class ClassDef(DefinitionBase): + def __init__(self, name: str) -> None: + super().__init__("class", 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 = "" + + +# Entry point for the RST generator. +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 + from ctypes import windll, c_int, byref # type: ignore stdout_handle = windll.kernel32.GetStdHandle(c_int(-11)) mode = c_int(0) @@ -466,6 +518,7 @@ def main(): # type: () -> None 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["yellow"] = "\x1b[93m" 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 "" @@ -491,7 +544,7 @@ def main(): # type: () -> None print("Checking for errors in the XML class reference...") - file_list = [] # type: List[str] + file_list: List[str] = [] for path in args.path: # Cut off trailing slashes so os.path.basename doesn't choke. @@ -515,7 +568,7 @@ def main(): # type: () -> None file_list.append(path) - classes = {} # type: Dict[str, ET.Element] + classes: Dict[str, Tuple[ET.Element, str]] = {} state = State() for cur_file in file_list: @@ -550,12 +603,29 @@ def main(): # type: () -> None # Create the output folder recursively if it doesn't already exist. os.makedirs(args.output, exist_ok=True) + print("Generating the RST class reference...") + 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) + print("") + + if state.num_warnings >= 2: + print( + "{}{} warnings were found in the class reference XML. Please check the messages above.{}".format( + STYLES["yellow"], state.num_warnings, STYLES["reset"] + ) + ) + elif state.num_warnings == 1: + print( + "{}1 warning was found in the class reference XML. Please check the messages above.{}".format( + STYLES["yellow"], STYLES["reset"] + ) + ) + if state.num_errors == 0: print("{}No errors found in the class reference XML.{}".format(STYLES["green"], STYLES["reset"])) if not args.dry_run: @@ -576,7 +646,20 @@ def main(): # type: () -> None exit(1) -def translate(string): # type: (str) -> str +# Common helpers. + + +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 print_warning(error: str, state: State) -> None: + print("{}{}WARNING:{} {}{}".format(STYLES["yellow"], STYLES["bold"], STYLES["regular"], error, STYLES["reset"])) + state.num_warnings += 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. @@ -584,7 +667,10 @@ def translate(string): # type: (str) -> str return strings_l10n.get(string, string) -def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, State, bool, str) -> None +# Generator methods. + + +def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: str) -> None: class_name = class_def.name if dry_run: @@ -635,8 +721,8 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S break f.write("\n\n") - # Descendents - inherited = [] + # Descendants + inherited: List[str] = [] for c in state.classes.values(): if c.inherits and c.inherits.strip() == class_name: inherited.append(c.name) @@ -651,12 +737,12 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Brief description if class_def.brief_description is not None: - f.write(rstize_text(class_def.brief_description.strip(), state) + "\n\n") + f.write(format_text_block(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(), state) + "\n\n") + f.write(format_text_block(class_def.description.strip(), class_def, state) + "\n\n") # Online tutorials if len(class_def.tutorials) > 0: @@ -667,7 +753,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Properties overview if len(class_def.properties) > 0: f.write(make_heading("Properties", "-")) - ml = [] # type: List[Tuple[str, str, str]] + 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 @@ -683,7 +769,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Constructors, Methods, Operators overview if len(class_def.constructors) > 0: f.write(make_heading("Constructors", "-")) - ml = [] + 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)) @@ -691,7 +777,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S if len(class_def.methods) > 0: f.write(make_heading("Methods", "-")) - ml = [] + 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)) @@ -699,7 +785,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S if len(class_def.operators) > 0: f.write(make_heading("Operators", "-")) - ml = [] + 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)) @@ -708,7 +794,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # Theme properties if len(class_def.theme_items) > 0: f.write(make_heading("Theme Properties", "-")) - pl = [] + 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 @@ -730,7 +816,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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") + f.write(format_text_block(signal.description.strip(), signal, state) + "\n\n") index += 1 @@ -760,7 +846,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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(), state))) + f.write(" --- " + indent_bullets(format_text_block(value.text.strip(), value, state))) f.write("\n\n") @@ -777,10 +863,11 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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(" --- " + format_text_block(constant.text.strip(), constant, state)) f.write("\n\n") + # Annotations if len(class_def.annotations) > 0: f.write(make_heading("Annotations", "-")) index = 0 @@ -793,11 +880,11 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S if i == 0: f.write(".. _class_{}_annotation_{}:\n\n".format(class_name, m.name.strip("@"))) - ret_type, signature = make_method_signature(class_def, m, "", state) - f.write("- {} {}\n\n".format(ret_type, signature)) + _, 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(), state) + "\n\n") + f.write(format_text_block(m.description.strip(), m, state) + "\n\n") index += 1 @@ -816,7 +903,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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 = [] + 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)) @@ -829,7 +916,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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") + f.write(format_text_block(property_def.text.strip(), property_def, state) + "\n\n") index += 1 @@ -850,7 +937,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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") + f.write(format_text_block(m.description.strip(), m, state) + "\n\n") index += 1 @@ -870,7 +957,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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") + f.write(format_text_block(m.description.strip(), m, state) + "\n\n") index += 1 @@ -894,7 +981,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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") + f.write(format_text_block(m.description.strip(), m, state) + "\n\n") index += 1 @@ -919,85 +1006,185 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S 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") + f.write(format_text_block(theme_item_def.text.strip(), theme_item_def, state) + "\n\n") index += 1 f.write(make_footer()) -def escape_rst(text, until_pos=-1): # type: (str, int) -> 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 +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 - # 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 +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" - return text + 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) -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("{}.xml: [" + code_type + "] without a closing tag.".format(state.current_class), state) - return None + return t - 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 +def make_method_signature( + class_def: ClassDef, definition: Union[AnnotationDef, MethodDef, SignalDef], ref_type: str, state: State +) -> Tuple[str, str]: + ret_type = "" - to_skip = 0 - while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == "\t": - to_skip += 1 + is_method_def = isinstance(definition, MethodDef) + if is_method_def: + ret_type = definition.return_type.to_rst(state) - if to_skip > indent_level: - print_error( - "{}.xml: Four spaces should be used for indentation within [{}].".format( - state.current_class, code_type - ), - 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) - if len(code_text[code_pos + to_skip + 1 :]) == 0: - code_text = code_text[:code_pos] + "\n" - code_pos += 1 + out += "**(**" + for i, arg in enumerate(definition.parameters): + if i > 0: + out += ", " 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)] + 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 rstize_text(text, state): # type: (str, State) -> str +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 + ">`__" + + +# Formatting helpers. + + +RESERVED_FORMATTING_TAGS = ["i", "b", "u", "code", "kbd", "center", "url", "br"] +RESERVED_CODEBLOCK_TAGS = ["codeblocks", "codeblock", "gdscript", "csharp"] +RESERVED_CROSSLINK_TAGS = ["method", "member", "signal", "constant", "enum", "annotation", "theme_item", "param"] + + +def is_in_tagset(tag_text: str, tagset: List[str]) -> bool: + for tag in tagset: + # Complete match. + if tag_text == tag: + return True + # Tag with arguments. + if tag_text.startswith(tag + " "): + return True + # Tag with arguments, special case for [url]. + if tag_text.startswith(tag + "="): + return True + + return False + + +def format_text_block( + text: str, + context: Union[DefinitionBase, None], + state: State, +) -> str: # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock" pos = 0 while True: @@ -1033,11 +1220,14 @@ def rstize_text(text, state): # type: (str, State) -> str next_brac_pos = text.find("[") text = escape_rst(text, next_brac_pos) + context_name = format_context_name(context) + # Handle [tags] inside_code = False + inside_code_tag = "" + inside_code_tabs = False pos = 0 tag_depth = 0 - previous_pos = 0 while True: pos = text.find("[", pos) if pos == -1: @@ -1054,188 +1244,337 @@ def rstize_text(text, state): # type: (str, State) -> str escape_pre = False escape_post = False + # Tag is a reference to a class. if tag_text in state.classes: if tag_text == state.current_class: - # We don't want references to the same class + # Don't create a link to the same class, format it as inline code. tag_text = "``{}``".format(tag_text) else: tag_text = make_type(tag_text, state) escape_pre = True escape_post = True - else: # command + + # Tag is a cross-reference or a formating directive. + else: 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" - if 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" - if 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" + # Anything identified as a tag inside of a code block is valid, + # unless it's a matching closing tag. + if inside_code: + # Exiting codeblocks and inline code tags. + + if inside_code_tag == cmd[1:]: + 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 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.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) + if cmd.startswith("/"): + print_warning( + '{}.xml: Potential error inside of a code tag, found a string that looks like a closing tag "[{}]" in {}.'.format( + state.current_class, cmd, context_name + ), + state, + ) - pre_text = text[:pos] - post_text = text[endurl_pos + 6 :] + tag_text = "[" + tag_text + "]" - 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 + # Entering codeblocks and inline code tags. - text = pre_text + tag_text + post_text - pos = len(pre_text) + len(tag_text) - previous_pos = pos - continue - elif cmd == "center": + elif cmd == "codeblocks": tag_depth += 1 - tag_text = "" - elif cmd == "/center": + tag_text = "\n.. tabs::" + inside_code_tabs = True + elif cmd == "/codeblocks": tag_depth -= 1 tag_text = "" - elif cmd == "codeblock": - tag_depth += 1 - tag_text = "\n::\n" - inside_code = True - elif cmd == "gdscript": + inside_code_tabs = False + + elif cmd == "codeblock" or cmd == "gdscript" or cmd == "csharp": tag_depth += 1 - tag_text = "\n .. code-tab:: gdscript\n" + + if cmd == "gdscript": + if not inside_code_tabs: + print_error( + "{}.xml: GDScript code block is used outside of [codeblocks] in {}.".format( + state.current_class, cmd, context_name + ), + state, + ) + tag_text = "\n .. code-tab:: gdscript\n" + elif cmd == "csharp": + if not inside_code_tabs: + print_error( + "{}.xml: C# code block is used outside of [codeblocks] in {}.".format( + state.current_class, cmd, context_name + ), + state, + ) + tag_text = "\n .. code-tab:: csharp\n" + else: + tag_text = "\n::\n" + inside_code = True - elif cmd == "csharp": + inside_code_tag = cmd + + elif cmd == "code": + tag_text = "``" 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 = "" + inside_code_tag = cmd + escape_pre = True + + # Cross-references to items in this or other class documentation pages. + elif is_in_tagset(cmd, RESERVED_CROSSLINK_TAGS): + link_target: str = "" + if space_pos >= 0: + link_target = tag_text[space_pos + 1 :].strip() + + if link_target == "": + print_error( + '{}.xml: Empty cross-reference link "{}" in {}.'.format(state.current_class, cmd, context_name), + state, + ) + tag_text = "" + else: + if ( + cmd.startswith("method") + or cmd.startswith("member") + or cmd.startswith("signal") + or cmd.startswith("constant") + or cmd.startswith("annotation") + or cmd.startswith("theme_item") + ): + if link_target.find(".") != -1: + ss = link_target.split(".") + if len(ss) > 2: + print_error( + '{}.xml: Bad reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + class_param, method_param = ss + + else: + class_param = state.current_class + method_param = link_target + + 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 reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_constructor" + + elif cmd.startswith("method"): + if method_param not in class_def.methods: + print_error( + '{}.xml: Unresolved method reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_method" + + elif cmd.startswith("operator"): + if method_param not in class_def.operators: + print_error( + '{}.xml: Unresolved operator reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_operator" + + elif cmd.startswith("member"): + if method_param not in class_def.properties: + print_error( + '{}.xml: Unresolved member reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_property" + + elif cmd.startswith("theme_item"): + if method_param not in class_def.theme_items: + print_error( + '{}.xml: Unresolved theme item reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + 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 reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_signal" + + elif cmd.startswith("annotation"): + if method_param not in class_def.annotations: + print_error( + '{}.xml: Unresolved annotation reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_annotation" + + elif cmd.startswith("constant"): + found = False + + # Search in the current class + search_class_defs = [class_def] + + if link_target.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 reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + ref_type = "_constant" + + else: + print_error( + '{}.xml: Unresolved type reference "{}" in method reference "{}" in {}.'.format( + state.current_class, class_param, link_target, context_name + ), + 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("enum"): + tag_text = make_enum(link_target, state) + escape_pre = True + escape_post = True + + elif cmd.startswith("param"): + valid_context = ( + isinstance(context, MethodDef) + or isinstance(context, SignalDef) + or isinstance(context, AnnotationDef) + ) + if not valid_context: + print_error( + '{}.xml: Argument reference "{}" used outside of method, signal, or annotation context in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + else: + context_params: List[ParameterDef] = context.parameters + found = False + for param_def in context_params: + if param_def.name == link_target: + found = True + break + if not found: + print_error( + '{}.xml: Unresolved argument reference "{}" in {}.'.format( + state.current_class, link_target, context_name + ), + state, + ) + + tag_text = "``{}``".format(link_target) + + # Formatting directives. + + elif is_in_tagset(cmd, ["url"]): + if cmd.startswith("url="): + # 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] in {}.".format( + state.current_class, context_name + ), + 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 + else: + print_error( + '{}.xml: Misformatted [url] tag "{}" in {}.'.format(state.current_class, cmd, context_name), + state, + ) + 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 == "center" or cmd == "/center": + if cmd == "/center": + tag_depth -= 1 + else: + tag_depth += 1 + tag_text = "" + elif cmd == "i" or cmd == "/i": if cmd == "/i": tag_depth -= 1 @@ -1244,6 +1583,7 @@ def rstize_text(text, state): # type: (str, State) -> str tag_depth += 1 escape_pre = True tag_text = "*" + elif cmd == "b" or cmd == "/b": if cmd == "/b": tag_depth -= 1 @@ -1252,6 +1592,7 @@ def rstize_text(text, state): # type: (str, State) -> str tag_depth += 1 escape_pre = True tag_text = "**" + elif cmd == "u" or cmd == "/u": if cmd == "/u": tag_depth -= 1 @@ -1260,25 +1601,31 @@ def rstize_text(text, state): # type: (str, State) -> str 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": + + elif cmd == "kbd" or 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 + if cmd == "/kbd": + tag_depth -= 1 + escape_post = True + else: + tag_text = ":kbd:" + tag_text + tag_depth += 1 + escape_pre = True + + # Invalid syntax checks. + elif cmd.startswith("/"): + print_error( + '{}.xml: Unrecognized closing tag "{}" in {}.'.format(state.current_class, cmd, context_name), state + ) + + tag_text = "[" + tag_text + "]" + else: - tag_text = make_type(tag_text, state) + print_error( + '{}.xml: Unrecognized opening tag "{}" in {}.'.format(state.current_class, cmd, context_name), state + ) + + tag_text = "``{}``".format(tag_text) escape_pre = True escape_post = True @@ -1310,17 +1657,98 @@ def rstize_text(text, state): # type: (str, State) -> str text = pre_text + tag_text + post_text pos = len(pre_text) + len(tag_text) - previous_pos = pos if tag_depth > 0: print_error( - "{}.xml: Tag depth mismatch: too many (or too little) open/close tags.".format(state.current_class), state + "{}.xml: Tag depth mismatch: too many (or too little) open/close tags in {}.".format( + state.current_class, context_name + ), + state, ) return text -def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterable[Tuple[str, ...]], bool) -> None +def format_context_name(context: Union[DefinitionBase, None]) -> str: + context_name: str = "unknown context" + if context is not None: + context_name = '{} "{}" description'.format(context.definition_name, context.name) + + return context_name + + +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 format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_columns: bool = False) -> None: if len(data) == 0: return @@ -1351,146 +1779,7 @@ def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterabl 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('{}.xml: Unresolved type "{}".'.format(state.current_class, klass), 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('{}.xml: Unresolved enum "{}".'.format(state.current_class, t), state) - - return t - - -def make_method_signature( - class_def, method_def, ref_type, state -): # type: (ClassDef, Union[MethodDef, SignalDef], str, State) -> Tuple[str, str] - ret_type = " " - - if isinstance(method_def, MethodDef): - ret_type = method_def.return_type.to_rst(state) - - out = "" - - if ref_type != "": - if ref_type == "operator": - out += ":ref:`{0}<class_{1}_{2}_{3}_{4}>` ".format( - method_def.name.replace("<", "\\<"), # So operator "<" gets correctly displayed. - class_def.name, - ref_type, - sanitize_operator_name(method_def.name, state), - method_def.return_type.type_name, - ) - else: - 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, l10n=True): # type: (str, str, bool) -> 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(): # type: () -> 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, 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` - # 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] + "`" - else: - # External link, for example: - # `http://enet.bespin.org/usergroup0.html` - if title != "": - return "`" + title + " <" + url + ">`__" - return "`" + url + " <" + url + ">`__" - - -def sanitize_operator_name(dirty_name, state): # type: (str, State) -> str +def sanitize_operator_name(dirty_name: str, state: State) -> str: clear_name = dirty_name.replace("operator ", "") if clear_name == "!=": @@ -1548,7 +1837,7 @@ def sanitize_operator_name(dirty_name, state): # type: (str, State) -> str return clear_name -def indent_bullets(text): # type: (str) -> str +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. |