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.py1401
1 files changed, 848 insertions, 553 deletions
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py
index 207eb7fabd..e5a0bbb008 100755
--- a/doc/tools/make_rst.py
+++ b/doc/tools/make_rst.py
@@ -19,7 +19,7 @@ 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
+# 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 = " -.,:;!?\\/'\")]}>"
@@ -29,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",
@@ -63,10 +69,24 @@ strings_l10n: Dict[str, str] = {}
STYLES: Dict[str, 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) -> None:
self.num_errors = 0
+ self.num_warnings = 0
self.classes: OrderedDict[str, ClassDef] = OrderedDict()
self.current_class: str = ""
@@ -97,7 +117,7 @@ class State:
property_name = property.attrib["name"]
if property_name in class_def.properties:
- print_error('{}.xml: Duplicate property "{}".'.format(class_name, property_name), self)
+ print_error(f'{class_name}.xml: Duplicate property "{property_name}".', self)
continue
type_name = TypeName.from_element(property)
@@ -105,7 +125,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(
@@ -210,7 +230,7 @@ class State:
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)
+ print_error(f'{class_name}.xml: Duplicate constant "{constant_name}".', self)
continue
class_def.constants[constant_name] = constant_def
@@ -254,7 +274,7 @@ class State:
signal_name = signal.attrib["name"]
if signal_name in class_def.signals:
- print_error('{}.xml: Duplicate signal "{}".'.format(class_name, signal_name), self)
+ print_error(f'{class_name}.xml: Duplicate signal "{signal_name}".', self)
continue
params = self.parse_params(signal, "signal")
@@ -277,16 +297,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(
- '{}.xml: Duplicate theme item "{}" of type "{}".'.format(
- class_name, theme_item_name, theme_item_data_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,
@@ -319,9 +337,7 @@ class State:
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
- ),
+ f'{self.current_class}.xml: Empty argument name in {context} "{root.attrib["name"]}" at position {param_index}.',
self,
)
@@ -332,7 +348,7 @@ class State:
return cast
def sort_classes(self) -> None:
- self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0]))
+ self.classes = OrderedDict(sorted(self.classes.items(), key=lambda t: t[0].lower()))
class TypeName:
@@ -353,7 +369,17 @@ class TypeName:
return cls(element.attrib["type"], element.get("enum"))
-class PropertyDef:
+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,
@@ -364,9 +390,8 @@ class PropertyDef:
default_value: Optional[str],
overrides: Optional[str],
) -> None:
- self.definition_name = "property"
+ super().__init__("property", name)
- self.name = name
self.type_name = type_name
self.setter = setter
self.getter = getter
@@ -375,25 +400,23 @@ class PropertyDef:
self.overrides = overrides
-class ParameterDef:
+class ParameterDef(DefinitionBase):
def __init__(self, name: str, type_name: TypeName, default_value: Optional[str]) -> None:
- self.definition_name = "parameter"
+ super().__init__("parameter", name)
- self.name = name
self.type_name = type_name
self.default_value = default_value
-class SignalDef:
+class SignalDef(DefinitionBase):
def __init__(self, name: str, parameters: List[ParameterDef], description: Optional[str]) -> None:
- self.definition_name = "signal"
+ super().__init__("signal", name)
- self.name = name
self.parameters = parameters
self.description = description
-class AnnotationDef:
+class AnnotationDef(DefinitionBase):
def __init__(
self,
name: str,
@@ -401,15 +424,14 @@ class AnnotationDef:
description: Optional[str],
qualifiers: Optional[str],
) -> None:
- self.definition_name = "annotation"
+ super().__init__("annotation", name)
- self.name = name
self.parameters = parameters
self.description = description
self.qualifiers = qualifiers
-class MethodDef:
+class MethodDef(DefinitionBase):
def __init__(
self,
name: str,
@@ -418,52 +440,47 @@ class MethodDef:
description: Optional[str],
qualifiers: Optional[str],
) -> None:
- self.definition_name = "method"
+ super().__init__("method", name)
- self.name = name
self.return_type = return_type
self.parameters = parameters
self.description = description
self.qualifiers = qualifiers
-class ConstantDef:
+class ConstantDef(DefinitionBase):
def __init__(self, name: str, value: str, text: Optional[str], bitfield: bool) -> None:
- self.definition_name = "constant"
+ super().__init__("constant", name)
- self.name = name
self.value = value
self.text = text
self.is_bitfield = bitfield
-class EnumDef:
+class EnumDef(DefinitionBase):
def __init__(self, name: str, bitfield: bool) -> None:
- self.definition_name = "enum"
+ super().__init__("enum", name)
- self.name = name
self.values: OrderedDict[str, ConstantDef] = OrderedDict()
self.is_bitfield = bitfield
-class ThemeItemDef:
+class ThemeItemDef(DefinitionBase):
def __init__(
self, name: str, type_name: TypeName, data_name: str, text: Optional[str], default_value: Optional[str]
) -> None:
- self.definition_name = "theme item"
+ super().__init__("theme item", name)
- self.name = name
self.type_name = type_name
self.data_name = data_name
self.text = text
self.default_value = default_value
-class ClassDef:
+class ClassDef(DefinitionBase):
def __init__(self, name: str) -> None:
- self.definition_name = "class"
+ super().__init__("class", name)
- self.name = name
self.constants: OrderedDict[str, ConstantDef] = OrderedDict()
self.enums: OrderedDict[str, EnumDef] = OrderedDict()
self.properties: OrderedDict[str, PropertyDef] = OrderedDict()
@@ -482,11 +499,7 @@ class ClassDef:
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
-
-
+# Entry point for the RST generator.
def main() -> None:
# Enable ANSI escape code support on Windows 10 and later (for colored console output).
# <https://bugs.python.org/issue29059>
@@ -520,6 +533,7 @@ def main() -> None:
should_color = args.color or (hasattr(sys.stdout, "isatty") and sys.stdout.isatty())
STYLES["red"] = "\x1b[91m" if should_color else ""
STYLES["green"] = "\x1b[92m" if should_color else ""
+ STYLES["yellow"] = "\x1b[93m" if should_color else ""
STYLES["bold"] = "\x1b[1m" if should_color else ""
STYLES["regular"] = "\x1b[22m" if should_color else ""
STYLES["reset"] = "\x1b[0m" if should_color else ""
@@ -531,7 +545,7 @@ def main() -> 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)
@@ -541,7 +555,7 @@ def main() -> 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...")
@@ -564,7 +578,7 @@ def main() -> 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)
@@ -576,17 +590,17 @@ def main() -> None:
try:
tree = ET.parse(cur_file)
except ET.ParseError as e:
- print_error("{}: Parse error while reading the 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" attribute missing from "doc".'.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(cur_file, name), state)
+ print_error(f'{cur_file}: Duplicate class "{name}".', state)
continue
classes[name] = (doc, cur_file)
@@ -595,7 +609,7 @@ def main() -> None:
try:
state.parse_class(data[0], data[1])
except Exception as e:
- print_error("{}.xml: Exception while parsing class: {}".format(name, e), state)
+ print_error(f"{name}.xml: Exception while parsing class: {e}", state)
state.sort_classes()
@@ -604,32 +618,67 @@ def main() -> 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)
+ 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("{}No errors found in the class reference XML.{}".format(STYLES["green"], STYLES["reset"]))
+ 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:
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"]
- )
+ f'{STYLES["red"]}{state.num_errors} errors were found in the class reference XML. Please check the messages above.{STYLES["reset"]}'
)
else:
print(
- "{}1 error was found in the class reference XML. Please check the messages above.{}".format(
- STYLES["red"], STYLES["reset"]
- )
+ f'{STYLES["red"]}1 error was found in the class reference XML. Please check the messages above.{STYLES["reset"]}'
)
exit(1)
+# 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.
@@ -638,13 +687,52 @@ def translate(string: str) -> str:
return strings_l10n.get(string, string)
+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")
@@ -652,28 +740,25 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# 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
# 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:
@@ -696,48 +781,64 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
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")
+ has_description = False
+
# Brief description
- if class_def.brief_description is not None:
- f.write(rstize_text(class_def.brief_description.strip(), class_def, 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(make_heading("Description", "-"))
- f.write(rstize_text(class_def.description.strip(), class_def, 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 <doc_updating_the_class_reference>`!"
+ )
+ + "\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")
+ f.write(f"- {make_link(url, title)}\n\n")
# Properties overview
+ ml: List[Tuple[Optional[str], ...]] = []
if len(class_def.properties) > 0:
f.write(make_heading("Properties", "-"))
- ml: List[Tuple[Optional[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}<class_{1}_property_{0}>`".format(property_def.name, property_def.overrides)
+ ref = f":ref:`{property_def.overrides}<class_{property_def.overrides}_property_{property_def.name}>`"
# 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}<class_{1}_property_{0}>`".format(property_def.name, class_name)
+ ref = f":ref:`{property_def.name}<class_{class_name}_property_{property_def.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], ...]] = []
+ ml = []
for method_list in class_def.constructors.values():
for m in method_list:
ml.append(make_method_signature(class_def, m, "constructor", state))
@@ -745,7 +846,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
if len(class_def.methods) > 0:
f.write(make_heading("Methods", "-"))
- ml: List[Tuple[Optional[str], ...]] = []
+ ml = []
for method_list in class_def.methods.values():
for m in method_list:
ml.append(make_method_signature(class_def, m, "method", state))
@@ -753,7 +854,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
if len(class_def.operators) > 0:
f.write(make_heading("Operators", "-"))
- ml: List[Tuple[Optional[str], ...]] = []
+ ml = []
for method_list in class_def.operators.values():
for m in method_list:
ml.append(make_method_signature(class_def, m, "operator", state))
@@ -764,9 +865,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
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
- )
+ ref = f":ref:`{theme_item_def.name}<class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}>`"
pl.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value))
format_table(f, pl, True)
@@ -779,12 +878,12 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
if index != 0:
f.write("----\n\n")
- f.write(".. _class_{}_signal_{}:\n\n".format(class_name, signal.name))
+ f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n")
_, signature = make_method_signature(class_def, signal, "", state)
- f.write("- {}\n\n".format(signature))
+ f.write(f"- {signature}\n\n")
if signal.description is not None and signal.description.strip() != "":
- f.write(rstize_text(signal.description.strip(), signal, state) + "\n\n")
+ f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n")
index += 1
@@ -797,24 +896,24 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
if index != 0:
f.write("----\n\n")
- f.write(".. _enum_{}_{}:\n\n".format(class_name, e.name))
+ f.write(f".. _enum_{class_name}_{e.name}:\n\n")
# Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it.
# As such I'll put them all above the list. Won't be perfect but better than making the list visually broken.
# As to why I'm not modifying the reference parser to directly link to the _enum label:
# If somebody gets annoyed enough to fix it, all existing references will magically improve.
for value in e.values.values():
- f.write(".. _class_{}_constant_{}:\n\n".format(class_name, value.name))
+ f.write(f".. _class_{class_name}_constant_{value.name}:\n\n")
if e.is_bitfield:
- f.write("flags **{}**:\n\n".format(e.name))
+ f.write(f"flags **{e.name}**:\n\n")
else:
- f.write("enum **{}**:\n\n".format(e.name))
+ f.write(f"enum **{e.name}**:\n\n")
for value in e.values.values():
- f.write("- **{}** = **{}**".format(value.name, value.value))
+ f.write(f"- **{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(f" --- {indent_bullets(format_text_block(value.text.strip(), value, state))}")
f.write("\n\n")
@@ -826,12 +925,12 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# 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))
+ f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n")
for constant in class_def.constants.values():
- f.write("- **{}** = **{}**".format(constant.name, constant.value))
+ f.write(f"- **{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(f" --- {format_text_block(constant.text.strip(), constant, state)}")
f.write("\n\n")
@@ -840,19 +939,27 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
f.write(make_heading("Annotations", "-"))
index = 0
- for method_list in class_def.annotations.values():
+ for method_list in class_def.annotations.values(): # type: ignore
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("@")))
+ f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n")
_, signature = make_method_signature(class_def, m, "", state)
- f.write("- {}\n\n".format(signature))
+ f.write(f"- {signature}\n\n")
if m.description is not None and m.description.strip() != "":
- f.write(rstize_text(m.description.strip(), m, 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 annotation. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+ )
+ + "\n\n"
+ )
index += 1
@@ -868,23 +975,31 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
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))
+ f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n")
+ f.write(f"- {property_def.type_name.to_rst(state)} **{property_def.name}**\n\n")
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))
+ 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" + ")"))
+ info.append(("*Setter*", f"{property_def.setter}(value)"))
if property_def.getter is not None and not property_def.getter.startswith("_"):
- info.append(("*" + "Getter" + "*", property_def.getter + "()"))
+ info.append(("*Getter*", f"{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")
+ 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 <doc_updating_the_class_reference>`!"
+ )
+ + "\n\n"
+ )
index += 1
@@ -899,13 +1014,21 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
f.write("----\n\n")
if i == 0:
- f.write(".. _class_{}_constructor_{}:\n\n".format(class_name, m.name))
+ f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n")
ret_type, signature = make_method_signature(class_def, m, "", state)
- f.write("- {} {}\n\n".format(ret_type, signature))
+ f.write(f"- {ret_type} {signature}\n\n")
if m.description is not None and m.description.strip() != "":
- f.write(rstize_text(m.description.strip(), m, 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 constructor. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+ )
+ + "\n\n"
+ )
index += 1
@@ -919,13 +1042,21 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
f.write("----\n\n")
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, "", state)
- f.write("- {} {}\n\n".format(ret_type, signature))
+ f.write(f"- {ret_type} {signature}\n\n")
if m.description is not None and m.description.strip() != "":
- f.write(rstize_text(m.description.strip(), m, 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 <doc_updating_the_class_reference>`!"
+ )
+ + "\n\n"
+ )
index += 1
@@ -937,20 +1068,25 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
for i, m in enumerate(method_list):
if index != 0:
f.write("----\n\n")
+ out = f".. _class_{class_name}_operator_{sanitize_operator_name(m.name, state)}"
+ for parameter in m.parameters:
+ out += f"_{parameter.type_name.type_name}"
+ out += f":\n\n"
+ f.write(out)
+ ret_type, signature = make_method_signature(class_def, m, "", state)
+ f.write(f"- {ret_type} {signature}\n\n")
- if i == 0:
+ if m.description is not None and m.description.strip() != "":
+ f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
+ else:
+ f.write(".. container:: contribute\n\n\t")
f.write(
- ".. _class_{}_operator_{}_{}:\n\n".format(
- class_name, sanitize_operator_name(m.name, state), m.return_type.type_name
+ translate(
+ "There is currently no description for this operator. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
)
+ + "\n\n"
)
- 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
@@ -962,99 +1098,253 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
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))
+ f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n")
+ f.write(f"- {theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**\n\n")
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))
+ 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")
+ 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 <doc_updating_the_class_reference>`!"
+ )
+ + "\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
+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}<class_{link_type}>`"
+ 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
- else:
- pos += 1
+def make_enum(t: str, state: State) -> str:
+ p = t.find(".")
+ if p >= 0:
+ c = t[0:p]
+ e = t[p + 1 :]
+ # Variant enums live in GlobalScope but still use periods.
+ if c == "Variant":
+ c = "@GlobalScope"
+ e = "Variant." + e
+ else:
+ c = state.current_class
+ e = t
+ if c in state.classes and e not in state.classes[c].enums:
+ c = "@GlobalScope"
- return text
+ if c in state.classes and e in state.classes[c].enums:
+ return f":ref:`{e}<enum_{c}_{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)
-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
+ return t
- code_text = post_text[len("[" + code_type + "]") : end_pos]
- post_text = post_text[end_pos:]
- # Remove extraneous tabs
- code_pos = 0
- while True:
- code_pos = code_text.find("\n", code_pos)
- if code_pos == -1:
- break
+def make_method_signature(
+ class_def: ClassDef, definition: Union[AnnotationDef, MethodDef, SignalDef], ref_type: str, state: State
+) -> Tuple[str, str]:
+ ret_type = ""
- to_skip = 0
- while code_pos + to_skip + 1 < len(code_text) and code_text[code_pos + to_skip + 1] == "\t":
- to_skip += 1
+ if isinstance(definition, MethodDef):
+ ret_type = definition.return_type.to_rst(state)
- if to_skip > indent_level:
- print_error(
- "{}.xml: Four spaces should be used for indentation within [{}].".format(
- state.current_class, code_type
- ),
- state,
- )
+ qualifiers = None
+ if isinstance(definition, (MethodDef, AnnotationDef)):
+ qualifiers = definition.qualifiers
- if len(code_text[code_pos + to_skip + 1 :]) == 0:
- code_text = code_text[:code_pos] + "\n"
- code_pos += 1
+ out = ""
+ if isinstance(definition, MethodDef) and ref_type != "":
+ if ref_type == "operator":
+ op_name = definition.name.replace("<", "\\<") # So operator "<" gets correctly displayed.
+ out += f":ref:`{op_name}<class_{class_def.name}_{ref_type}_{sanitize_operator_name(definition.name, state)}"
+ for parameter in definition.parameters:
+ out += f"_{parameter.type_name.type_name}"
+ out += f">` "
else:
- code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1 :]
- code_pos += 5 - to_skip
- return ("\n[" + code_type + "]" + code_text + post_text, len("\n[" + code_type + "]" + code_text))
+ out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>` "
+ else:
+ out += f"**{definition.name}** "
+
+ out += "**(**"
+ for i, arg in enumerate(definition.parameters):
+ if i > 0:
+ out += ", "
+ else:
+ out += " "
+ out += f"{arg.type_name.to_rst(state)} {arg.name}"
-def rstize_text(
+ 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 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.")
+ constructor_msg = translate("This method is used to construct a type.")
+ static_msg = translate(
+ "This method doesn't need an instance to be called, so it can be called directly using the class name."
+ )
+ operator_msg = translate("This method describes a valid operator to use with this type as left-hand operand.")
+
+ 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".. |constructor| replace:: :abbr:`constructor ({constructor_msg})`\n"
+ f".. |static| replace:: :abbr:`static ({static_msg})`\n"
+ f".. |operator| replace:: :abbr:`operator ({operator_msg})`\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", "annotation", "theme_item", "param"]
+
+
+def is_in_tagset(tag_text: str, tagset: List[str]) -> bool:
+ for tag in tagset:
+ # Complete match.
+ if tag_text == tag:
+ return True
+ # Tag with arguments.
+ if tag_text.startswith(tag + " "):
+ return True
+ # Tag with arguments, special case for [url].
+ if tag_text.startswith(tag + "="):
+ return True
+
+ return False
+
+
+def format_text_block(
text: str,
- context: Union[ClassDef, SignalDef, ConstantDef, AnnotationDef, PropertyDef, MethodDef, ThemeItemDef, None],
+ context: Union[DefinitionBase, None],
state: State,
) -> str:
# Linebreak + tabs in the XML should become two line breaks unless in a "codeblock"
@@ -1081,19 +1371,23 @@ def rstize_text(
result = format_codeblock(block_type, post_text, indent_level, state)
if result is None:
return ""
- text = pre_text + result[0]
+ 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
while True:
@@ -1112,240 +1406,303 @@ def rstize_text(
escape_pre = False
escape_post = False
+ # Tag is a reference to a class.
if tag_text in state.classes:
if tag_text == state.current_class:
- # We don't want references to the same class
- tag_text = "``{}``".format(tag_text)
+ # Don't create a link to the same class, format it as inline code.
+ 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" 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
+ # 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
-
- 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 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,
+ )
+
+ tag_text = f"[{tag_text}]"
- if not found:
- print_error('{}.xml: Unresolved constant "{}".'.format(state.current_class, param), state)
- ref_type = "_constant"
+ # Entering codeblocks and inline code tags.
+
+ 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 == "codeblock" or cmd == "gdscript" or cmd == "csharp":
+ tag_depth += 1
+ 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:
- print_error(
- '{}.xml: Unresolved type reference "{}" in method reference "{}".'.format(
- state.current_class, class_param, param
- ),
- state,
- )
+ tag_text = "\n::\n"
- 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)
+ inside_code = True
+ inside_code_tag = cmd
+
+ elif cmd == "code":
+ tag_text = "``"
+ tag_depth += 1
+ inside_code = True
+ inside_code_tag = cmd
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)
+ # 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(
- "{}.xml: Empty argument reference in {}.".format(state.current_class, context_name),
+ f'{state.current_class}.xml: Empty cross-reference link "{cmd}" in {context_name}.',
state,
)
+ tag_text = ""
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)
+ if (
+ cmd.startswith("method")
+ or cmd.startswith("constructor")
+ or cmd.startswith("operator")
+ or cmd.startswith("member")
+ or cmd.startswith("signal")
+ or cmd.startswith("annotation")
+ 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("constructor") and method_param not in class_def.constructors:
+ print_error(
+ f'{state.current_class}.xml: Unresolved constructor reference "{link_target}" in {context_name}.',
+ state,
+ )
+
+ elif cmd.startswith("operator") and method_param not in class_def.operators:
+ print_error(
+ f'{state.current_class}.xml: Unresolved operator 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("annotation") and method_param not in class_def.annotations:
+ print_error(
+ f'{state.current_class}.xml: Unresolved annotation 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
- 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:
+ 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(
- '{}.xml: Unresolved argument reference "{}" in {} "{}" description.'.format(
- state.current_class, param_name, context.definition_name, context.name
- ),
+ f'{state.current_class}.xml: Unresolved type reference "{class_param}" in method reference "{link_target}" in {context_name}.',
state,
)
- if param_name == "":
- tag_text = ""
+ repl_text = method_param
+ if class_param != state.current_class:
+ repl_text = f"{class_param}.{method_param}"
+ tag_text = f":ref:`{repl_text}<class_{class_param}{ref_type}_{method_param}>`"
+ escape_pre = True
+ escape_post = True
+
+ elif cmd.startswith("enum"):
+ tag_text = make_enum(link_target, state)
+ escape_pre = True
+ escape_post = True
+
+ elif cmd.startswith("param"):
+ valid_context = isinstance(context, (MethodDef, SignalDef, AnnotationDef))
+ if not valid_context:
+ print_error(
+ f'{state.current_class}.xml: Argument reference "{link_target}" used outside of method, signal, or annotation 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:
- 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
+ f'{state.current_class}.xml: Misformatted [url] tag "{cmd}" 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
- 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 == "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
@@ -1354,6 +1711,7 @@ def rstize_text(
tag_depth += 1
escape_pre = True
tag_text = "*"
+
elif cmd == "b" or cmd == "/b":
if cmd == "/b":
tag_depth -= 1
@@ -1362,6 +1720,7 @@ def rstize_text(
tag_depth += 1
escape_pre = True
tag_text = "**"
+
elif cmd == "u" or cmd == "/u":
if cmd == "/u":
tag_depth -= 1
@@ -1370,25 +1729,27 @@ def rstize_text(
tag_depth += 1
escape_pre = True
tag_text = ""
- elif cmd == "code":
- tag_text = "``"
- tag_depth += 1
- inside_code = True
- escape_pre = True
- elif cmd == "kbd":
- tag_text = ":kbd:`"
- tag_depth += 1
- escape_pre = True
- elif cmd == "/kbd":
+
+ elif cmd == "kbd" or cmd == "/kbd":
tag_text = "`"
- tag_depth -= 1
- escape_post = True
- elif cmd.startswith("enum "):
- tag_text = make_enum(cmd[5:], state)
- escape_pre = True
- escape_post = True
+ if cmd == "/kbd":
+ tag_depth -= 1
+ escape_post = True
+ else:
+ tag_text = ":kbd:" + tag_text
+ tag_depth += 1
+ escape_pre = True
+
+ # Invalid syntax checks.
+ elif cmd.startswith("/"):
+ print_error(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
@@ -1404,7 +1765,7 @@ def rstize_text(
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
@@ -1413,7 +1774,7 @@ def rstize_text(
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
@@ -1423,12 +1784,90 @@ def rstize_text(
if tag_depth > 0:
print_error(
- "{}.xml: Tag depth mismatch: too many (or too little) open/close tags.".format(state.current_class), state
+ f"{state.current_class}.xml: Tag depth mismatch: too many (or too few) open/close tags in {context_name}.",
+ state,
)
return text
+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
@@ -1453,157 +1892,13 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_
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("\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 ", "")
@@ -1657,7 +1952,7 @@ def sanitize_operator_name(dirty_name: str, state: State) -> str:
else:
clear_name = "xxx"
- print_error('Unsupported operator type "{}", please add the missing rule.'.format(dirty_name), state)
+ print_error(f'Unsupported operator type "{dirty_name}", please add the missing rule.', state)
return clear_name
@@ -1676,7 +1971,7 @@ def indent_bullets(text: str) -> str:
pos += 1
if pos < len(line) and line[pos] in bullet_points:
- lines[line_index] = line[:pos] + "\t" + line[pos:]
+ lines[line_index] = f"{line[:pos]}\t{line[pos:]}"
return "".join(lines)