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