Adjust `make_rst.py` for GDScript documentation

doc/tools/make_rst.py

@@ -911,7 +911,7 @@ def get_git_branch() -> str:
 def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: str) -> None:
     class_name = class_def.name
     with open(
-        os.devnull if dry_run else os.path.join(output_dir, f"class_{class_name.lower()}.rst"),
+        os.devnull if dry_run else os.path.join(output_dir, f"class_{sanitize_class_name(class_name, True)}.rst"),
         "w",
         encoding="utf-8",
         newline="\n",
@@ -937,7 +937,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
         f.write(f".. XML source: {source_github_url}.\n\n")
 
         # Document reference id and header.
-        f.write(f".. _class_{class_name}:\n\n")
+        f.write(f".. _class_{sanitize_class_name(class_name)}:\n\n")
         f.write(make_heading(class_name, "=", False))
 
         f.write(make_deprecated_experimental(class_def, state))
@@ -1041,13 +1041,11 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
                 type_rst = property_def.type_name.to_rst(state)
                 default = property_def.default_value
                 if default is not None and property_def.overrides:
-                    ref = (
-                        f":ref:`{property_def.overrides}<class_{property_def.overrides}_property_{property_def.name}>`"
-                    )
+                    ref = f":ref:`{property_def.overrides}<class_{sanitize_class_name(property_def.overrides)}_property_{property_def.name}>`"
                     # Not using translate() for now as it breaks table formatting.
                     ml.append((type_rst, property_def.name, f"{default} (overrides {ref})"))
                 else:
-                    ref = f":ref:`{property_def.name}<class_{class_name}_property_{property_def.name}>`"
+                    ref = f":ref:`{property_def.name}<class_{sanitize_class_name(class_name)}_property_{property_def.name}>`"
                     ml.append((type_rst, ref, default))
 
             format_table(f, ml, True)
@@ -1093,7 +1091,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
             ml = []
             for theme_item_def in class_def.theme_items.values():
-                ref = f":ref:`{theme_item_def.name}<class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}>`"
+                ref = f":ref:`{theme_item_def.name}<class_{sanitize_class_name(class_name)}_theme_{theme_item_def.data_name}_{theme_item_def.name}>`"
                 ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value))
 
             format_table(f, ml, True)
@@ -1114,7 +1112,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 # Create signal signature and anchor point.
 
-                signal_anchor = f"class_{class_name}_signal_{signal.name}"
+                signal_anchor = f"class_{sanitize_class_name(class_name)}_signal_{signal.name}"
                 f.write(f".. _{signal_anchor}:\n\n")
                 self_link = f":ref:`🔗<{signal_anchor}>`"
                 f.write(".. rst-class:: classref-signal\n\n")
@@ -1153,7 +1151,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 # Create enumeration signature and anchor point.
 
-                enum_anchor = f"enum_{class_name}_{e.name}"
+                enum_anchor = f"enum_{sanitize_class_name(class_name)}_{e.name}"
                 f.write(f".. _{enum_anchor}:\n\n")
                 self_link = f":ref:`🔗<{enum_anchor}>`"
                 f.write(".. rst-class:: classref-enumeration\n\n")
@@ -1166,7 +1164,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
                 for value in e.values.values():
                     # Also create signature and anchor point for each enum constant.
 
-                    f.write(f".. _class_{class_name}_constant_{value.name}:\n\n")
+                    f.write(f".. _class_{sanitize_class_name(class_name)}_constant_{value.name}:\n\n")
                     f.write(".. rst-class:: classref-enumeration-constant\n\n")
 
                     f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\n\n")
@@ -1199,7 +1197,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
             for constant in class_def.constants.values():
                 # Create constant signature and anchor point.
 
-                constant_anchor = f"class_{class_name}_constant_{constant.name}"
+                constant_anchor = f"class_{sanitize_class_name(class_name)}_constant_{constant.name}"
                 f.write(f".. _{constant_anchor}:\n\n")
                 self_link = f":ref:`🔗<{constant_anchor}>`"
                 f.write(".. rst-class:: classref-constant\n\n")
@@ -1239,7 +1237,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                     self_link = ""
                     if i == 0:
-                        annotation_anchor = f"class_{class_name}_annotation_{m.name}"
+                        annotation_anchor = f"class_{sanitize_class_name(class_name)}_annotation_{m.name}"
                         f.write(f".. _{annotation_anchor}:\n\n")
                         self_link = f" :ref:`🔗<{annotation_anchor}>`"
 
@@ -1280,7 +1278,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 # Create property signature and anchor point.
 
-                property_anchor = f"class_{class_name}_property_{property_def.name}"
+                property_anchor = f"class_{sanitize_class_name(class_name)}_property_{property_def.name}"
                 f.write(f".. _{property_anchor}:\n\n")
                 self_link = f":ref:`🔗<{property_anchor}>`"
                 f.write(".. rst-class:: classref-property\n\n")
@@ -1348,7 +1346,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                     self_link = ""
                     if i == 0:
-                        constructor_anchor = f"class_{class_name}_constructor_{m.name}"
+                        constructor_anchor = f"class_{sanitize_class_name(class_name)}_constructor_{m.name}"
                         f.write(f".. _{constructor_anchor}:\n\n")
                         self_link = f" :ref:`🔗<{constructor_anchor}>`"
 
@@ -1394,7 +1392,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
                         method_qualifier = ""
                         if m.name.startswith("_"):
                             method_qualifier = "private_"
-                        method_anchor = f"class_{class_name}_{method_qualifier}method_{m.name}"
+                        method_anchor = f"class_{sanitize_class_name(class_name)}_{method_qualifier}method_{m.name}"
                         f.write(f".. _{method_anchor}:\n\n")
                         self_link = f" :ref:`🔗<{method_anchor}>`"
 
@@ -1435,7 +1433,9 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                     # Create operator signature and anchor point.
 
-                    operator_anchor = f"class_{class_name}_operator_{sanitize_operator_name(m.name, state)}"
+                    operator_anchor = (
+                        f"class_{sanitize_class_name(class_name)}_operator_{sanitize_operator_name(m.name, state)}"
+                    )
                     for parameter in m.parameters:
                         operator_anchor += f"_{parameter.type_name.type_name}"
                     f.write(f".. _{operator_anchor}:\n\n")
@@ -1477,7 +1477,9 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 # Create theme property signature and anchor point.
 
-                theme_item_anchor = f"class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}"
+                theme_item_anchor = (
+                    f"class_{sanitize_class_name(class_name)}_theme_{theme_item_def.data_name}_{theme_item_def.name}"
+                )
                 f.write(f".. _{theme_item_anchor}:\n\n")
                 self_link = f":ref:`🔗<{theme_item_anchor}>`"
                 f.write(".. rst-class:: classref-themeproperty\n\n")
@@ -1515,7 +1517,7 @@ def make_type(klass: str, state: State) -> str:
 
     def resolve_type(link_type: str) -> str:
         if link_type in state.classes:
-            return f":ref:`{link_type}<class_{link_type}>`"
+            return f":ref:`{link_type}<class_{sanitize_class_name(link_type)}>`"
         else:
             print_error(f'{state.current_class}.xml: Unresolved type "{link_type}".', state)
             return f"``{link_type}``"
@@ -1533,7 +1535,7 @@ def make_type(klass: str, state: State) -> str:
 
 
 def make_enum(t: str, is_bitfield: bool, state: State) -> str:
-    p = t.find(".")
+    p = t.rfind(".")
     if p >= 0:
         c = t[0:p]
         e = t[p + 1 :]
@@ -1551,9 +1553,9 @@ def make_enum(t: str, is_bitfield: bool, state: State) -> str:
         if is_bitfield:
             if not state.classes[c].enums[e].is_bitfield:
                 print_error(f'{state.current_class}.xml: Enum "{t}" is not bitfield.', state)
-            return f"|bitfield|\\[:ref:`{e}<enum_{c}_{e}>`\\]"
+            return f"|bitfield|\\[:ref:`{e}<enum_{sanitize_class_name(c)}_{e}>`\\]"
         else:
-            return f":ref:`{e}<enum_{c}_{e}>`"
+            return f":ref:`{e}<enum_{sanitize_class_name(c)}_{e}>`"
 
     print_error(f'{state.current_class}.xml: Unresolved enum "{t}".', state)
 
@@ -1576,7 +1578,7 @@ def make_method_signature(
     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)}"
+            out += f":ref:`{op_name}<class_{sanitize_class_name(class_def.name)}_{ref_type}_{sanitize_operator_name(definition.name, state)}"
             for parameter in definition.parameters:
                 out += f"_{parameter.type_name.type_name}"
             out += ">`"
@@ -1584,9 +1586,9 @@ def make_method_signature(
             ref_type_qualifier = ""
             if definition.name.startswith("_"):
                 ref_type_qualifier = "private_"
-            out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type_qualifier}{ref_type}_{definition.name}>`"
+            out += f":ref:`{definition.name}<class_{sanitize_class_name(class_def.name)}_{ref_type_qualifier}{ref_type}_{definition.name}>`"
         else:
-            out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>`"
+            out += f":ref:`{definition.name}<class_{sanitize_class_name(class_def.name)}_{ref_type}_{definition.name}>`"
     else:
         out += f"**{definition.name}**"
 
@@ -1774,13 +1776,15 @@ def make_rst_index(grouped_classes: Dict[str, List[str]], dry_run: bool, output_
                 f.write("\n")
 
                 if group_name in CLASS_GROUPS_BASE:
-                    f.write(f"    class_{CLASS_GROUPS_BASE[group_name].lower()}\n")
+                    f.write(f"    class_{sanitize_class_name(CLASS_GROUPS_BASE[group_name], True)}\n")
 
                 for class_name in grouped_classes[group_name]:
-                    if group_name in CLASS_GROUPS_BASE and CLASS_GROUPS_BASE[group_name].lower() == class_name.lower():
+                    if group_name in CLASS_GROUPS_BASE and sanitize_class_name(
+                        CLASS_GROUPS_BASE[group_name], True
+                    ) == sanitize_class_name(class_name, True):
                         continue
 
-                    f.write(f"    class_{class_name.lower()}\n")
+                    f.write(f"    class_{sanitize_class_name(class_name, True)}\n")
 
                 f.write("\n")
 
@@ -2261,7 +2265,7 @@ def format_text_block(
                         repl_text = target_name
                         if target_class_name != state.current_class:
                             repl_text = f"{target_class_name}.{target_name}"
-                        tag_text = f":ref:`{repl_text}<class_{target_class_name}{ref_type}_{target_name}>`"
+                        tag_text = f":ref:`{repl_text}<class_{sanitize_class_name(target_class_name)}{ref_type}_{target_name}>`"
                         escape_pre = True
                         escape_post = True
 
@@ -2574,6 +2578,13 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_
     f.write("\n")
 
 
+def sanitize_class_name(dirty_name: str, is_file_name=False) -> str:
+    if is_file_name:
+        return dirty_name.lower().replace('"', "").replace("/", "--")
+    else:
+        return dirty_name.replace('"', "").replace("/", "_").replace(".", "_")
+
+
 def sanitize_operator_name(dirty_name: str, state: State) -> str:
     clear_name = dirty_name.replace("operator ", "")
 

modules/gdscript/editor/gdscript_docgen.cpp

@@ -139,10 +139,11 @@ void GDScriptDocGen::_doctype_from_gdtype(const GDType &p_gdtype, String &r_type
 			r_type = "int";
 			r_enum = String(p_gdtype.native_type).replace("::", ".");
 			if (r_enum.begins_with("res://")) {
-				r_enum = r_enum.trim_prefix("res://");
 				int dot_pos = r_enum.rfind_char('.');
 				if (dot_pos >= 0) {
-					r_enum = r_enum.left(dot_pos).quote() + r_enum.substr(dot_pos);
+					r_enum = _get_script_name(r_enum.left(dot_pos)) + r_enum.substr(dot_pos);
+				} else {
+					r_enum = _get_script_name(r_enum);
 				}
 			}
 			return;
@@ -407,7 +408,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				method_doc.experimental_message = m_func->doc_data.experimental_message;
 				method_doc.qualifiers = m_func->is_static ? "static" : "";
 
-				if (m_func->return_type) {
+				if (func_name == "_init") {
+					method_doc.return_type = "void";
+				} else if (m_func->return_type) {
 					// `m_func->return_type->get_datatype()` is a metatype.
 					_doctype_from_gdtype(m_func->get_datatype(), method_doc.return_type, method_doc.return_enum, true);
 				} else if (!m_func->body->has_return) {