diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index d11de94800d..ebe96ddb7b6 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -811,7 +811,7 @@ The indentation style to use (tabs or spaces). - [b]Note:[/b] The [url=$DOCS_URL/getting_started/scripting/gdscript/gdscript_styleguide.html]GDScript style guide[/url] recommends using tabs for indentation. It is advised to change this setting only if you need to work on a project that currently uses spaces for indentation. + [b]Note:[/b] The [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_styleguide.html]GDScript style guide[/url] recommends using tabs for indentation. It is advised to change this setting only if you need to work on a project that currently uses spaces for indentation. If [code]true[/code], allows drag-and-dropping text in the script editor to move text. Disable this if you find yourself accidentally drag-and-dropping text in the script editor. diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 5f2d81e9ab2..0d08d8e9f93 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -1183,7 +1183,7 @@ The minimum size of the window in pixels (without counting window manager decorations). Does not affect fullscreen mode. Set to [code](0, 0)[/code] to reset to the system's default value. [b]Note:[/b] By default, the project window has a minimum size of [code]Vector2(64, 64)[/code]. This prevents issues that can arise when the window is resized to a near-zero size. - + The current screen orientation. diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index bf79a8dfbe2..c50586095fd 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -4,23 +4,22 @@ 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 -# 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(#.*)?$") -# Based on reStructedText inline markup recognition rules +# Based on reStructuredText inline markup recognition rules # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules MARKUP_ALLOWED_PRECEDENT = " -:/'\"<([{" MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>" @@ -30,6 +29,12 @@ MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>" # 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 = [ + "All classes", + "Globals", + "Nodes", + "Resources", + "Other objects", + "Variant types", "Description", "Tutorials", "Properties", @@ -51,122 +56,36 @@ BASE_STRINGS = [ "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 doesn't need an instance to be called, so it can be called directly using the class name.", ] -strings_l10n = {} +strings_l10n: Dict[str, str] = {} +STYLES: Dict[str, str] = {} -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, 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 - - -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_GROUPS: Dict[str, str] = { + "global": "Globals", + "node": "Nodes", + "resource": "Resources", + "object": "Other objects", + "variant": "Variant types", +} +CLASS_GROUPS_BASE: Dict[str, str] = { + "node": "Node", + "resource": "Resource", + "object": "Object", +} 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 __init__(self) -> None: + self.num_errors = 0 + 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 @@ -191,7 +110,7 @@ class State: property_name = property.attrib["name"] if property_name in class_def.properties: - print_error("Duplicate property '{}', file: {}".format(property_name, class_name), self) + print_error(f'{class_name}.xml: Duplicate property "{property_name}".', self) continue type_name = TypeName.from_element(property) @@ -199,7 +118,7 @@ class State: getter = property.get("getter") or None default_value = property.get("default") or None if default_value is not None: - default_value = "``{}``".format(default_value) + default_value = f"``{default_value}``" overrides = property.get("overrides") or None property_def = PropertyDef( @@ -222,7 +141,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 @@ -246,7 +165,7 @@ class State: 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) + print_error(f'{class_name}.xml: Duplicate constant "{constant_name}".', self) continue class_def.constants[constant_name] = constant_def @@ -256,7 +175,7 @@ class State: enum_def = class_def.enums[enum] else: - enum_def = EnumDef(enum) + enum_def = EnumDef(enum, TypeName("int", enum)) class_def.enums[enum] = enum_def enum_def.values[constant_name] = constant_def @@ -269,10 +188,10 @@ class State: signal_name = signal.attrib["name"] if signal_name in class_def.signals: - print_error("Duplicate signal '{}', file: {}".format(signal_name, class_name), self) + print_error(f'{class_name}.xml: Duplicate signal "{signal_name}".', self) continue - params = parse_arguments(signal) + params = self.parse_params(signal, "signal") desc_element = signal.find("description") signal_desc = None @@ -292,16 +211,14 @@ class State: 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 - ), + f'{class_name}.xml: Duplicate theme item "{theme_item_name}" of type "{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) + default_value = f"``{default_value}``" theme_item_def = ThemeItemDef( theme_item_name, @@ -310,7 +227,7 @@ class State: theme_item.text, default_value, ) - class_def.theme_items[theme_item_id] = theme_item_def + class_def.theme_items[theme_item_name] = theme_item_def tutorials = class_root.find("tutorials") if tutorials is not None: @@ -320,27 +237,176 @@ 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.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0])) + self.current_class = "" + + def parse_params(self, root: ET.Element, context: str) -> List["ParameterDef"]: + param_elements = root.findall("argument") + 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( + f'{self.current_class}.xml: Empty argument name in {context} "{root.attrib["name"]}" at position {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].lower())) -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 - params[index] = ParameterDef(param_name, type_name, default) + 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) - cast = params # type: List[ParameterDef] - - return cast + @classmethod + def from_element(cls, element: ET.Element) -> "TypeName": + return cls(element.attrib["type"], element.get("enum")) -def main(): # type: () -> None +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 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 + + +class ConstantDef(DefinitionBase): + def __init__(self, name: str, value: str, text: Optional[str]) -> None: + super().__init__("constant", name) + + self.value = value + self.text = text + + +class EnumDef(DefinitionBase): + def __init__(self, name: str, type_name: TypeName) -> None: + super().__init__("enum", name) + + self.type_name = type_name + self.values: OrderedDict[str, ConstantDef] = OrderedDict() + + +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.methods: OrderedDict[str, List[MethodDef]] = OrderedDict() + self.signals: OrderedDict[str, SignalDef] = 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). + # + 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.") @@ -348,7 +414,7 @@ def main(): # type: () -> None parser.add_argument( "--color", action="store_true", - help="Ignored. Supported for forward compatibility.", + 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.") @@ -359,6 +425,14 @@ def main(): # type: () -> None ) 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["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 "" + # Retrieve heading translations for the given language. if not args.dry_run and args.lang != "en": lang_file = os.path.join( @@ -366,7 +440,7 @@ def main(): # type: () -> None ) if os.path.exists(lang_file): try: - import polib + import polib # type: ignore except ImportError: print("Base template strings localization requires `polib`.") exit(1) @@ -376,11 +450,11 @@ def main(): # type: () -> None 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(f'No PO file at "{lang_file}" for language "{args.lang}".') 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. @@ -399,29 +473,29 @@ def main(): # type: () -> None elif os.path.isfile(path): if not path.endswith(".xml"): - print("Got non-.xml file '{}' in input, skipping.".format(path)) + print(f'Got non-.xml file "{path}" in input, skipping.') continue 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: try: tree = ET.parse(cur_file) except ET.ParseError as e: - print_error("Parse error reading file '{}': {}".format(cur_file, e), state) + print_error(f"{cur_file}: Parse error while reading the file: {e}", state) continue doc = tree.getroot() if "version" not in doc.attrib: - print_error("Version missing from 'doc', file: {}".format(cur_file), state) + print_error(f'{cur_file}: "version" attribute missing from "doc".', state) continue name = doc.attrib["name"] if name in classes: - print_error("Duplicate class '{}'".format(name), state) + print_error(f'{cur_file}: Duplicate class "{name}".', state) continue classes[name] = (doc, cur_file) @@ -430,7 +504,7 @@ def main(): # type: () -> None try: state.parse_class(data[0], data[1]) except Exception as e: - print_error("Exception while parsing class '{}': {}".format(name, e), state) + print_error(f"{name}.xml: Exception while parsing class: {e}", state) state.sort_classes() @@ -439,22 +513,68 @@ 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...") + + grouped_classes: Dict[str, List[str]] = {} + 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.") + group_name = get_class_group(class_def, state) + + if group_name not in grouped_classes: + grouped_classes[group_name] = [] + grouped_classes[group_name].append(class_name) + + print("") + print("Generating the index file...") + + make_rst_index(grouped_classes, args.dry_run, args.output) + + print("") + + if state.num_warnings >= 2: + print( + f'{STYLES["yellow"]}{state.num_warnings} warnings were found in the class reference XML. Please check the messages above.{STYLES["reset"]}' + ) + elif state.num_warnings == 1: + print( + f'{STYLES["yellow"]}1 warning was found in the class reference XML. Please check the messages above.{STYLES["reset"]}' + ) + + if state.num_errors == 0: + print(f'{STYLES["green"]}No errors found in the class reference XML.{STYLES["reset"]}') if not args.dry_run: - print("Wrote reStructuredText files for each class to: %s" % args.output) + print(f"Wrote reStructuredText files for each class to: {args.output}") else: - print("Errors were found in the class reference XML. Please check the messages above.") + if state.num_errors >= 2: + print( + f'{STYLES["red"]}{state.num_errors} errors were found in the class reference XML. Please check the messages above.{STYLES["reset"]}' + ) + else: + print( + f'{STYLES["red"]}1 error was found in the class reference XML. Please check the messages above.{STYLES["reset"]}' + ) exit(1) -def translate(string): # type: (str) -> str +# Common helpers. + + +def print_error(error: str, state: State) -> None: + print(f'{STYLES["red"]}{STYLES["bold"]}ERROR:{STYLES["regular"]} {error}{STYLES["reset"]}') + state.num_errors += 1 + + +def print_warning(warning: str, state: State) -> None: + print(f'{STYLES["yellow"]}{STYLES["bold"]}WARNING:{STYLES["regular"]} {warning}{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. @@ -462,13 +582,52 @@ 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 +def get_git_branch() -> str: + if hasattr(version, "docs") and version.docs != "latest": + return version.docs + + return "master" + + +def get_class_group(class_def: ClassDef, state: State) -> str: + group_name = "variant" + class_name = class_def.name + + if class_name.startswith("@"): + group_name = "global" + elif class_def.inherits: + inherits = class_def.inherits.strip() + + while inherits in state.classes: + if inherits == "Node": + group_name = "node" + break + if inherits == "Resource": + group_name = "resource" + break + if inherits == "Object": + group_name = "object" + break + + inode = state.classes[inherits].inherits + if inode: + inherits = inode.strip() + else: + break + + return group_name + + +# 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: 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") + f = open(os.path.join(output_dir, f"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") @@ -476,28 +635,26 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S # 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 - + git_branch = get_git_branch() 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) + source_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/{source_xml_path}" + generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" 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") + f.write(f".. Generator: {generator_github_url}.\n") + f.write(f".. XML source: {source_github_url}.\n\n") # Document reference id and header. - f.write(".. _class_" + class_name + ":\n\n") + f.write(f".. _class_{class_name}:\n\n") f.write(make_heading(class_name, "=", False)) - # Inheritance tree + ### INHERITANCE TREE ### + # Ascendants if class_def.inherits: inherits = class_def.inherits.strip() - f.write("**" + translate("Inherits:") + "** ") + f.write(f'**{translate("Inherits:")}** ') first = True while inherits in state.classes: if not first: @@ -513,135 +670,204 @@ 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) if len(inherited): - f.write("**" + translate("Inherited By:") + "** ") + f.write(f'**{translate("Inherited By:")}** ') for i, child in enumerate(inherited): if i > 0: f.write(", ") f.write(make_type(child, state)) f.write("\n\n") + ### INTRODUCTION ### + + has_description = False + # Brief description - if class_def.brief_description is not None: - f.write(rstize_text(class_def.brief_description.strip(), state) + "\n\n") + if class_def.brief_description is not None and class_def.brief_description.strip() != "": + has_description = True + + f.write(f"{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() != "": + has_description = True + + f.write(".. rst-class:: classref-introduction-group\n\n") f.write(make_heading("Description", "-")) - f.write(rstize_text(class_def.description.strip(), state) + "\n\n") + + f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n") + + if not has_description: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this class. Please help us by :ref:`contributing one `!" + ) + + "\n\n" + ) # Online tutorials if len(class_def.tutorials) > 0: + f.write(".. rst-class:: classref-introduction-group\n\n") f.write(make_heading("Tutorials", "-")) - for url, title in class_def.tutorials: - f.write("- " + make_link(url, title) + "\n\n") - # Properties overview + for url, title in class_def.tutorials: + f.write(f"- {make_link(url, title)}\n\n") + + ### REFERENCE TABLES ### + + # Reused container for reference tables. + ml: List[Tuple[Optional[str], ...]] = [] + + # Properties reference table if len(class_def.properties) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Properties", "-")) - ml = [] # type: List[Tuple[str, str, str]] + + ml = [] 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}`".format(property_def.name, property_def.overrides) + ref = f":ref:`{property_def.overrides}`" # Not using translate() for now as it breaks table formatting. - ml.append((type_rst, property_def.name, default + " " + "(overrides %s)" % ref)) + ml.append((type_rst, property_def.name, f"{default} (overrides {ref})")) else: - ref = ":ref:`{0}`".format(property_def.name, class_name) + ref = f":ref:`{property_def.name}`" ml.append((type_rst, ref, default)) + format_table(f, ml, True) - # Methods overview + # Methods reference tables if len(class_def.methods) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") 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)) + ml.append(make_method_signature(class_def, m, "method", state)) + format_table(f, ml) - # Theme properties + # Theme properties reference table if len(class_def.theme_items) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Theme Properties", "-")) - pl = [] - for theme_item_def in class_def.theme_items.values(): - ref = ":ref:`{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 + ml = [] + for theme_item_def in class_def.theme_items.values(): + ref = f":ref:`{theme_item_def.name}`" + ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) + + format_table(f, ml, True) + + ### DETAILED DESCRIPTIONS ### + + # Signal descriptions if len(class_def.signals) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Signals", "-")) + index = 0 for signal in class_def.signals.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) - 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)) + # Create signal signature and anchor point. + + f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") + f.write(".. rst-class:: classref-signal\n\n") + + _, signature = make_method_signature(class_def, signal, "", state) + f.write(f"{signature}\n\n") + + # Add signal description, or a call to action if it's missing. if signal.description is not None and signal.description.strip() != "": - f.write(rstize_text(signal.description.strip(), state) + "\n\n") + f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this signal. Please help us by :ref:`contributing one `!" + ) + + "\n\n" + ) index += 1 - # Enums + # Enumeration descriptions if len(class_def.enums) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Enumerations", "-")) + index = 0 for e in class_def.enums.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) - f.write(".. _enum_{}_{}:\n\n".format(class_name, e.name)) - # Sphinx seems to divide the bullet list into individual
    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)) + # Create enumeration signature and anchor point. + + f.write(f".. _enum_{class_name}_{e.name}:\n\n") + f.write(".. rst-class:: classref-enumeration\n\n") + + f.write(f"enum **{e.name}**:\n\n") - f.write("enum **{}**:\n\n".format(e.name)) for value in e.values.values(): - f.write("- **{}** = **{}**".format(value.name, value.value)) + # Also create signature and anchor point for each enum constant. + + f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") + f.write(".. rst-class:: classref-enumeration-constant\n\n") + + f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\n\n") + + # Add enum constant description. + 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(f"{format_text_block(value.text.strip(), value, state)}") f.write("\n\n") index += 1 - # Constants + # Constant descriptions if len(class_def.constants) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Constants", "-")) - # Sphinx seems to divide the bullet list into individual
      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)) + # Create constant signature and anchor point. + + f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") + f.write(".. rst-class:: classref-constant\n\n") + + f.write(f"**{constant.name}** = ``{constant.value}``\n\n") + + # Add enum constant description. + if constant.text is not None and constant.text.strip() != "": - f.write(" --- " + rstize_text(constant.text.strip(), state)) + f.write(f"{format_text_block(constant.text.strip(), constant, state)}") f.write("\n\n") # Property descriptions if any(not p.overrides for p in class_def.properties.values()) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Property Descriptions", "-")) + index = 0 for property_def in class_def.properties.values(): @@ -649,112 +875,380 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S continue if index != 0: - f.write("----\n\n") + f.write(make_separator()) - 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)) + # Create property signature and anchor point. - info = [] - # Not using translate() for now as it breaks table formatting. + f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") + f.write(".. rst-class:: classref-property\n\n") + + property_default = "" 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 + "()")) + property_default = f" = {property_def.default_value}" + f.write(f"{property_def.type_name.to_rst(state)} **{property_def.name}**{property_default}\n\n") - if len(info) > 0: - format_table(f, info) + # Create property setter and getter records. + + property_setget = "" + + if property_def.setter is not None and not property_def.setter.startswith("_"): + property_setter = make_setter_signature(class_def, property_def, state) + property_setget += f"- {property_setter}\n" + + if property_def.getter is not None and not property_def.getter.startswith("_"): + property_getter = make_getter_signature(class_def, property_def, state) + property_setget += f"- {property_getter}\n" + + if property_setget != "": + f.write(".. rst-class:: classref-property-setget\n\n") + f.write(property_setget) + f.write("\n") + + # Add property description, or a call to action if it's missing. 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(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this property. Please help us by :ref:`contributing one `!" + ) + + "\n\n" + ) index += 1 # Method descriptions if len(class_def.methods) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") 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") + f.write(make_separator()) + + # Create method signature and anchor point. if i == 0: - f.write(".. _class_{}_method_{}:\n\n".format(class_name, m.name)) + f.write(f".. _class_{class_name}_method_{m.name}:\n\n") - ret_type, signature = make_method_signature(class_def, m, False, state) - f.write("- {} {}\n\n".format(ret_type, signature)) + f.write(".. rst-class:: classref-method\n\n") + + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write(f"{ret_type} {signature}\n\n") + + # Add method description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": - f.write(rstize_text(m.description.strip(), state) + "\n\n") + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this method. Please help us by :ref:`contributing one `!" + ) + + "\n\n" + ) index += 1 # Theme property descriptions if len(class_def.theme_items) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") 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(make_separator()) - 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)) + # Create theme property signature and anchor point. - info = [] + f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n") + f.write(".. rst-class:: classref-themeproperty\n\n") + + theme_item_default = "" 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)) + theme_item_default = f" = {theme_item_def.default_value}" + f.write(f"{theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**{theme_item_default}\n\n") - if len(info) > 0: - format_table(f, info) + # Add theme property description, or a call to action if it's missing. 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(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this theme property. Please help us by :ref:`contributing one `!" + ) + + "\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 f":ref:`{klass}`" + print_error(f'{state.current_class}.xml: Unresolved type "{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 +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 f":ref:`{e}`" + + # Don't fail for `Vector3.Axis`, as this enum is a special case which is expected not to be resolved. + if f"{c}.{e}" != "Vector3.Axis": + print_error(f'{state.current_class}.xml: Unresolved enum "{t}".', state) + + return t + + +def make_method_signature( + class_def: ClassDef, definition: Union[MethodDef, SignalDef], ref_type: str, state: State +) -> Tuple[str, str]: + ret_type = "" + + if isinstance(definition, MethodDef): + ret_type = definition.return_type.to_rst(state) + + qualifiers = None + if isinstance(definition, MethodDef): + qualifiers = definition.qualifiers + + out = "" + if isinstance(definition, MethodDef) and ref_type != "": + out += f":ref:`{definition.name}` " + else: + out += f"**{definition.name}** " + + out += "**(**" + for i, arg in enumerate(definition.parameters): + if i > 0: + out += ", " else: - pos += 1 + out += " " - return text + out += f"{arg.type_name.to_rst(state)} {arg.name}" + + if arg.default_value is not None: + out += f"={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 += f" |{qualifier}|" + + return ret_type, out -def rstize_text(text, state): # type: (str, State) -> str +def make_setter_signature(class_def: ClassDef, property_def: PropertyDef, state: State) -> str: + if property_def.setter is None: + return "" + + # If setter is a method available as a method definition, we use that. + if property_def.setter in class_def.methods: + setter = class_def.methods[property_def.setter][0] + # Otherwise we fake it with the information we have available. + else: + setter_params: List[ParameterDef] = [] + setter_params.append(ParameterDef("value", property_def.type_name, None)) + setter = MethodDef(property_def.setter, TypeName("void"), setter_params, None, None) + + ret_type, signature = make_method_signature(class_def, setter, "", state) + return f"{ret_type} {signature}" + + +def make_getter_signature(class_def: ClassDef, property_def: PropertyDef, state: State) -> str: + if property_def.getter is None: + return "" + + # If getter is a method available as a method definition, we use that. + if property_def.getter in class_def.methods: + getter = class_def.methods[property_def.getter][0] + # Otherwise we fake it with the information we have available. + else: + getter_params: List[ParameterDef] = [] + getter = MethodDef(property_def.getter, property_def.type_name, getter_params, None, None) + + ret_type, signature = make_method_signature(class_def, getter, "", state) + return f"{ret_type} {signature}" + + +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 f"{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. + virtual_msg = translate("This method should typically be overridden by the user to have any effect.") + const_msg = translate("This method has no side effects. It doesn't modify any of the instance's member variables.") + vararg_msg = translate("This method accepts any number of arguments after the ones described here.") + static_msg = translate( + "This method doesn't need an instance to be called, so it can be called directly using the class name." + ) + + return ( + f".. |virtual| replace:: :abbr:`virtual ({virtual_msg})`\n" + f".. |const| replace:: :abbr:`const ({const_msg})`\n" + f".. |vararg| replace:: :abbr:`vararg ({vararg_msg})`\n" + f".. |static| replace:: :abbr:`static ({static_msg})`\n" + ) + + +def make_separator(section_level: bool = False) -> str: + separator_class = "item" + if section_level: + separator_class = "section" + + return f".. rst-class:: classref-{separator_class}-separator\n\n----\n\n" + + +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 f"`{title} <../{groups[0]}.html{groups[1]}>`__" + return f"`{groups[1]} <../{groups[0]}.html{groups[1]}>`__ in :doc:`../{groups[0]}`" + elif match.lastindex == 1: + # Doc reference, for example: + # `Math` + if title != "": + return f":doc:`{title} <../{groups[0]}>`" + return f":doc:`../{groups[0]}`" + + # External link, for example: + # `http://enet.bespin.org/usergroup0.html` + if title != "": + return f"`{title} <{url}>`__" + return f"`{url} <{url}>`__" + + +def make_rst_index(grouped_classes: Dict[str, List[str]], dry_run: bool, output_dir: str) -> None: + + if dry_run: + f = open(os.devnull, "w", encoding="utf-8") + else: + f = open(os.path.join(output_dir, "index.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 = get_git_branch() + generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" + + f.write(".. DO NOT EDIT THIS FILE!!!\n") + f.write(".. Generated automatically from Godot engine sources.\n") + f.write(f".. Generator: {generator_github_url}.\n\n") + + f.write(".. _doc_class_reference:\n\n") + + main_title = translate("All classes") + f.write(f"{main_title}\n") + f.write(f"{'=' * len(main_title)}\n\n") + + for group_name in CLASS_GROUPS: + if group_name in grouped_classes: + group_title = translate(CLASS_GROUPS[group_name]) + + f.write(f"{group_title}\n") + f.write(f"{'=' * len(group_title)}\n\n") + + f.write(".. toctree::\n") + f.write(" :maxdepth: 1\n") + f.write(f" :name: toc-class-ref-{group_name}s\n") + f.write("\n") + + if group_name in CLASS_GROUPS_BASE: + f.write(f" class_{CLASS_GROUPS_BASE[group_name].lower()}\n") + + for class_name in grouped_classes[group_name]: + f.write(f" class_{class_name.lower()}\n") + + f.write("\n") + + +# 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", "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: @@ -770,57 +1264,34 @@ def rstize_text(text, state): # type: (str, State) -> str post_text = text[pos + 1 :] # Handle codeblocks - if post_text.startswith("[codeblock]"): - end_pos = post_text.find("[/codeblock]") - if end_pos == -1: - print_error("[codeblock] without a closing tag, file: {}".format(state.current_class), state) + 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 "" - - code_text = post_text[len("[codeblock]") : 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 [codeblock], 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 - - text = pre_text + "\n[codeblock]" + code_text + post_text - pos += len("\n[codeblock]" + code_text) - indent_level + text = f"{pre_text}{result[0]}" + pos += result[1] - indent_level # Handle normal text else: - text = pre_text + "\n\n" + post_text + text = f"{pre_text}\n\n{post_text}" pos += 2 - indent_level 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: @@ -837,153 +1308,282 @@ def rstize_text(text, state): # type: (str, State) -> str escape_pre = False escape_post = False - if tag_text in state.classes: + # Tag is a reference to a class. + if tag_text in state.classes and not inside_code: if tag_text == state.current_class: - # We don't want references to the same class - tag_text = "``{}``".format(tag_text) + # Don't create a link to the same class, format it as strong emphasis. + tag_text = f"**{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 formatting directive. + else: cmd = tag_text space_pos = tag_text.find(" ") - if cmd == "/codeblock": - 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 + # 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: - class_param = state.current_class - method_param = param + if cmd.startswith("/"): + print_warning( + f'{state.current_class}.xml: Potential error inside of a code tag, found a string that looks like a closing tag "[{cmd}]" in {context_name}.', + state, + ) - 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" + tag_text = f"[{tag_text}]" - 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" + # Entering codeblocks and inline code tags. - 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 == "codeblocks": + tag_depth += 1 + tag_text = "\n.. tabs::" + inside_code_tabs = True + elif cmd == "/codeblocks": + tag_depth -= 1 + tag_text = "" + inside_code_tabs = False - elif cmd.startswith("constant"): - found = False + elif cmd == "codeblock" or cmd == "gdscript" or cmd == "csharp": + tag_depth += 1 - # Search in the current class - search_class_defs = [class_def] + if cmd == "gdscript": + if not inside_code_tabs: + print_error( + f"{state.current_class}.xml: GDScript code block is used outside of [codeblocks] in {context_name}.", + state, + ) + tag_text = "\n .. code-tab:: gdscript\n" + elif cmd == "csharp": + if not inside_code_tabs: + print_error( + f"{state.current_class}.xml: C# code block is used outside of [codeblocks] in {context_name}.", + state, + ) + tag_text = "\n .. code-tab:: csharp\n" + else: + tag_text = "\n::\n" - if param.find(".") == -1: - # Also search in @GlobalScope as a last resort if no class was specified - search_class_defs.append(state.classes["@GlobalScope"]) + inside_code = True + inside_code_tag = cmd - for search_class_def in search_class_defs: - if method_param in search_class_def.constants: - class_param = search_class_def.name - found = True + elif cmd == "code": + tag_text = "``" + tag_depth += 1 + inside_code = True + inside_code_tag = cmd + escape_pre = True - else: - for enum in search_class_def.enums.values(): - if method_param in enum.values: + # Cross-references to items in this or other class documentation pages. + elif is_in_tagset(cmd, RESERVED_CROSSLINK_TAGS): + link_type: str = "" + link_target: str = "" + if space_pos >= 0: + link_type = tag_text[:space_pos] + link_target = tag_text[space_pos + 1 :].strip() + + if link_target == "": + print_error( + f'{state.current_class}.xml: Empty cross-reference link "{cmd}" in {context_name}.', + state, + ) + tag_text = "" + else: + if ( + cmd.startswith("method") + or cmd.startswith("member") + or cmd.startswith("signal") + or cmd.startswith("theme_item") + or cmd.startswith("constant") + ): + if link_target.find(".") != -1: + ss = link_target.split(".") + if len(ss) > 2: + print_error( + f'{state.current_class}.xml: Bad reference "{link_target}" in {context_name}.', + state, + ) + class_param, method_param = ss + + else: + class_param = state.current_class + method_param = link_target + + # Default to the tag command name. This works by default for most tags, + # but member and theme_item have special cases. + ref_type = "_{}".format(link_type) + if link_type == "member": + ref_type = "_property" + + if class_param in state.classes: + class_def = state.classes[class_param] + + if cmd.startswith("method") and method_param not in class_def.methods: + print_error( + f'{state.current_class}.xml: Unresolved method reference "{link_target}" in {context_name}.', + state, + ) + + elif cmd.startswith("member") and method_param not in class_def.properties: + print_error( + f'{state.current_class}.xml: Unresolved member reference "{link_target}" in {context_name}.', + state, + ) + + elif cmd.startswith("signal") and method_param not in class_def.signals: + print_error( + f'{state.current_class}.xml: Unresolved signal reference "{link_target}" in {context_name}.', + state, + ) + + elif cmd.startswith("theme_item"): + if method_param not in class_def.theme_items: + print_error( + f'{state.current_class}.xml: Unresolved theme item reference "{link_target}" in {context_name}.', + state, + ) + else: + # Needs theme data type to be properly linked, which we cannot get without a class. + name = class_def.theme_items[method_param].data_name + ref_type = f"_theme_{name}" + + 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 - break - if not found: - print_error("Unresolved constant '{}', file: {}".format(param, state.current_class), state) - ref_type = "_constant" + 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( + f'{state.current_class}.xml: Unresolved constant reference "{link_target}" in {context_name}.', + state, + ) + + else: + print_error( + f'{state.current_class}.xml: Unresolved type reference "{class_param}" in method reference "{link_target}" in {context_name}.', + state, + ) + + repl_text = method_param + if class_param != state.current_class: + repl_text = f"{class_param}.{method_param}" + tag_text = f":ref:`{repl_text}`" + 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, SignalDef)) + if not valid_context: + print_error( + f'{state.current_class}.xml: Argument reference "{link_target}" used outside of method, or signal context in {context_name}.', + state, + ) + else: + context_params: List[ParameterDef] = context.parameters # type: ignore + found = False + for param_def in context_params: + if param_def.name == link_target: + found = True + break + if not found: + print_error( + f'{state.current_class}.xml: Unresolved argument reference "{link_target}" in {context_name}.', + state, + ) + + tag_text = f"``{link_target}``" + escape_pre = True + escape_post = True + + # 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( + f"{state.current_class}.xml: Tag depth mismatch for [url]: no closing [/url] in {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( - "Unresolved type reference '{}' in method reference '{}', file: {}".format( - class_param, param, state.current_class - ), + f'{state.current_class}.xml: Misformatted [url] tag "{cmd}" in {context_name}.', state, ) - repl_text = method_param - if class_param != state.current_class: - repl_text = "{}.{}".format(class_param, method_param) - tag_text = ":ref:`{}`".format(repl_text, class_param, ref_type, method_param) - escape_pre = True - escape_post = True - elif cmd.find("image=") == 0: - tag_text = "" # '![](' + cmd[6:] + ')' - 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( - "Tag depth mismatch for [url]: no closing [/url], file: {}".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) - previous_pos = pos - 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 == "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 @@ -992,6 +1592,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 @@ -1000,6 +1601,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 @@ -1008,23 +1610,27 @@ 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 - elif cmd == "/kbd": + + elif cmd == "kbd" or cmd == "/kbd": tag_text = "`" - tag_depth -= 1 - 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(f'{state.current_class}.xml: Unrecognized closing tag "{cmd}" in {context_name}.', state) + + tag_text = f"[{tag_text}]" + else: - tag_text = make_type(tag_text, state) + print_error(f'{state.current_class}.xml: Unrecognized opening tag "{cmd}" in {context_name}.', state) + + tag_text = f"``{tag_text}``" escape_pre = True escape_post = True @@ -1040,7 +1646,7 @@ def rstize_text(text, state): # type: (str, State) -> str 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 :] + post_text = f"{post_text[:iter_pos]}\*{post_text[iter_pos + 1 :]}" iter_pos += 2 iter_pos = 0 @@ -1049,25 +1655,109 @@ def rstize_text(text, state): # type: (str, State) -> str 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 :] + post_text = f"{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) + print_error( + f"{state.current_class}.xml: Tag depth mismatch: too many (or too few) open/close tags in {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 = f'{context.definition_name} "{context.name}" description' + + 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 = f"{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 = f"{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 = f"{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(f"{state.current_class}.xml: [{code_type}] without a closing tag.", state) + return None + + code_text = post_text[len(f"[{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( + f"{state.current_class}.xml: Four spaces should be used for indentation within [{code_type}].", + state, + ) + + if len(code_text[code_pos + to_skip + 1 :]) == 0: + code_text = f"{code_text[:code_pos]}\n" + code_pos += 1 + else: + code_text = f"{code_text[:code_pos]}\n {code_text[code_pos + to_skip + 1 :]}" + code_pos += 5 - to_skip + return (f"\n[{code_type}]{code_text}{post_text}", len(f"\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 + f.write(".. table::\n") + f.write(" :widths: auto\n\n") + + # Calculate the width of each column first, we will use this information + # to properly format RST-style tables. column_sizes = [0] * len(data[0]) for row in data: for i, text in enumerate(row): @@ -1075,171 +1765,34 @@ def format_table(f, data, remove_empty_columns=False): # type: (TextIO, Iterabl if text_length > column_sizes[i]: column_sizes[i] = text_length + # Each table row is wrapped in two separators, consecutive rows share the same separator. + # All separators, or rather borders, have the same shape and content. We compose it once, + # then reuse it. + sep = "" for size in column_sizes: if size == 0 and remove_empty_columns: continue - sep += "+" + "-" * (size + 2) + sep += "+" + "-" * (size + 2) # Content of each cell is padded by 1 on each side. sep += "+\n" - f.write(sep) + # Draw the first separator. + f.write(f" {sep}") + + # Draw each row and close it with a separator. 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 += f' {(text or "").ljust(column_sizes[i])} |' row_text += "\n" - f.write(row_text) - f.write(sep) + + f.write(f" {row_text}") + f.write(f" {sep}") + f.write("\n") -def make_type(t, state): # type: (str, State) -> str - if t in state.classes: - return ":ref:`{0}`".format(t) - print_error("Unresolved type '{}', file: {}".format(t, state.current_class), state) - return t - - -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 not c in state.classes and c.startswith("_"): - c = c[1:] # Remove the underscore prefix - - if c in state.classes and e in state.classes[c].enums: - return ":ref:`{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}` ".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" - ) - # 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 indent_bullets(text): # type: (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/editor/doc/doc_data.cpp b/editor/doc/doc_data.cpp index 0cbc1a758c1..dc6340daa95 100644 --- a/editor/doc/doc_data.cpp +++ b/editor/doc/doc_data.cpp @@ -384,6 +384,9 @@ void DocData::generate(bool p_basic_types) { found_type = true; if (retinfo.type == Variant::INT && retinfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { prop.enumeration = retinfo.class_name; + if (prop.enumeration.begins_with("_")) { //proxy class + prop.enumeration = prop.enumeration.substr(1, prop.enumeration.length()); + } prop.type = "int"; } else if (retinfo.class_name != StringName()) { prop.type = retinfo.class_name;