diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 38e3edef2f1..51b6b9befcc 100755 --- a/doc/tools/make_rst.py +++ b/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}`" - ) + ref = f":ref:`{property_def.overrides}`" # 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}`" + ref = f":ref:`{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}`" + ref = f":ref:`{theme_item_def.name}`" ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) format_table(f, ml, True) @@ -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}`" + return f":ref:`{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}`\\]" + return f"|bitfield|\\[:ref:`{e}`\\]" else: - return f":ref:`{e}`" + return f":ref:`{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}`" + out += f":ref:`{definition.name}`" else: - out += f":ref:`{definition.name}`" + out += f":ref:`{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}`" + tag_text = f":ref:`{repl_text}`" 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 ", "") diff --git a/modules/gdscript/editor/gdscript_docgen.cpp b/modules/gdscript/editor/gdscript_docgen.cpp index 3a5a88d3567..a6742820b57 100644 --- a/modules/gdscript/editor/gdscript_docgen.cpp +++ b/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) {