godotengine/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2025-11-07 12:30:27 +00:00
Code Releases Wiki Activity

Adjust make_rst.py for GDScript documentation

Browse Source
This commit is contained in:
Danil Alexeev
2024-11-30 11:48:14 +03:00
parent 0eadbdb5d0
commit ba943e4481
2 changed files with 45 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
doc/tools/make_rst.py
View File

@@ -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: def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: str) -> None:
class_name = class_def.name class_name = class_def.name
with open( 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", "w",
encoding="utf-8", encoding="utf-8",
newline="\n", 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") f.write(f".. XML source: {source_github_url}.\n\n")
# Document reference id and header. # 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_heading(class_name, "=", False))
f.write(make_deprecated_experimental(class_def, state)) 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) type_rst = property_def.type_name.to_rst(state)
default = property_def.default_value default = property_def.default_value
if default is not None and property_def.overrides: if default is not None and property_def.overrides:
ref = ( ref = f":ref:`{property_def.overrides}<class_{sanitize_class_name(property_def.overrides)}_property_{property_def.name}>`"
f":ref:`{property_def.overrides}<class_{property_def.overrides}_property_{property_def.name}>`"
)
# Not using translate() for now as it breaks table formatting. # Not using translate() for now as it breaks table formatting.
ml.append((type_rst, property_def.name, f"{default} (overrides {ref})")) ml.append((type_rst, property_def.name, f"{default} (overrides {ref})"))
else: 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)) ml.append((type_rst, ref, default))
format_table(f, ml, True) format_table(f, ml, True)
@@ -1093,7 +1091,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
ml = [] ml = []
for theme_item_def in class_def.theme_items.values(): 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)) ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value))
format_table(f, ml, True) 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. # 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") f.write(f".. _{signal_anchor}:\n\n")
self_link = f":ref:`🔗<{signal_anchor}>`" self_link = f":ref:`🔗<{signal_anchor}>`"
f.write(".. rst-class:: classref-signal\n\n") 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. # 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") f.write(f".. _{enum_anchor}:\n\n")
self_link = f":ref:`🔗<{enum_anchor}>`" self_link = f":ref:`🔗<{enum_anchor}>`"
f.write(".. rst-class:: classref-enumeration\n\n") 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(): for value in e.values.values():
# Also create signature and anchor point for each enum constant. # 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(".. rst-class:: classref-enumeration-constant\n\n")
f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\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(): for constant in class_def.constants.values():
# Create constant signature and anchor point. # 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") f.write(f".. _{constant_anchor}:\n\n")
self_link = f":ref:`🔗<{constant_anchor}>`" self_link = f":ref:`🔗<{constant_anchor}>`"
f.write(".. rst-class:: classref-constant\n\n") 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 = "" self_link = ""
if i == 0: 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") f.write(f".. _{annotation_anchor}:\n\n")
self_link = f" :ref:`🔗<{annotation_anchor}>`" 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. # 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") f.write(f".. _{property_anchor}:\n\n")
self_link = f":ref:`🔗<{property_anchor}>`" self_link = f":ref:`🔗<{property_anchor}>`"
f.write(".. rst-class:: classref-property\n\n") 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 = "" self_link = ""
if i == 0: 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") f.write(f".. _{constructor_anchor}:\n\n")
self_link = f" :ref:`🔗<{constructor_anchor}>`" 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 = "" method_qualifier = ""
if m.name.startswith("_"): if m.name.startswith("_"):
method_qualifier = "private_" 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") f.write(f".. _{method_anchor}:\n\n")
self_link = f" :ref:`🔗<{method_anchor}>`" 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. # 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: for parameter in m.parameters:
operator_anchor += f"_{parameter.type_name.type_name}" operator_anchor += f"_{parameter.type_name.type_name}"
f.write(f".. _{operator_anchor}:\n\n") 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. # 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") f.write(f".. _{theme_item_anchor}:\n\n")
self_link = f":ref:`🔗<{theme_item_anchor}>`" self_link = f":ref:`🔗<{theme_item_anchor}>`"
f.write(".. rst-class:: classref-themeproperty\n\n") 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: def resolve_type(link_type: str) -> str:
if link_type in state.classes: 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: else:
print_error(f'{state.current_class}.xml: Unresolved type "{link_type}".', state) print_error(f'{state.current_class}.xml: Unresolved type "{link_type}".', state)
return f"``{link_type}``" 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: def make_enum(t: str, is_bitfield: bool, state: State) -> str:
p = t.find(".") p = t.rfind(".")
if p >= 0: if p >= 0:
c = t[0:p] c = t[0:p]
e = t[p + 1 :] e = t[p + 1 :]
@@ -1551,9 +1553,9 @@ def make_enum(t: str, is_bitfield: bool, state: State) -> str:
if is_bitfield: if is_bitfield:
if not state.classes[c].enums[e].is_bitfield: if not state.classes[c].enums[e].is_bitfield:
print_error(f'{state.current_class}.xml: Enum "{t}" is not bitfield.', state) 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: 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) 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 isinstance(definition, MethodDef) and ref_type != "":
if ref_type == "operator": if ref_type == "operator":
op_name = definition.name.replace("<", "\\<") # So operator "<" gets correctly displayed. 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: for parameter in definition.parameters:
out += f"_{parameter.type_name.type_name}" out += f"_{parameter.type_name.type_name}"
out += ">`" out += ">`"
@@ -1584,9 +1586,9 @@ def make_method_signature(
ref_type_qualifier = "" ref_type_qualifier = ""
if definition.name.startswith("_"): if definition.name.startswith("_"):
ref_type_qualifier = "private_" 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: 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: else:
out += f"**{definition.name}**" 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") f.write("\n")
if group_name in CLASS_GROUPS_BASE: 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]: 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 continue
f.write(f" class_{class_name.lower()}\n") f.write(f" class_{sanitize_class_name(class_name, True)}\n")
f.write("\n") f.write("\n")
@@ -2261,7 +2265,7 @@ def format_text_block(
repl_text = target_name repl_text = target_name
if target_class_name != state.current_class: if target_class_name != state.current_class:
repl_text = f"{target_class_name}.{target_name}" 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_pre = True
escape_post = True escape_post = True
@@ -2574,6 +2578,13 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_
f.write("\n") 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: def sanitize_operator_name(dirty_name: str, state: State) -> str:
clear_name = dirty_name.replace("operator ", "") clear_name = dirty_name.replace("operator ", "")

9
modules/gdscript/editor/gdscript_docgen.cpp
View File

@@ -139,10 +139,11 @@ void GDScriptDocGen::_doctype_from_gdtype(const GDType &p_gdtype, String &r_type
r_type = "int"; r_type = "int";
r_enum = String(p_gdtype.native_type).replace("::", "."); r_enum = String(p_gdtype.native_type).replace("::", ".");
if (r_enum.begins_with("res://")) { if (r_enum.begins_with("res://")) {
r_enum = r_enum.trim_prefix("res://");
int dot_pos = r_enum.rfind_char('.'); int dot_pos = r_enum.rfind_char('.');
if (dot_pos >= 0) { 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; 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.experimental_message = m_func->doc_data.experimental_message;
method_doc.qualifiers = m_func->is_static ? "static" : ""; 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. // `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); _doctype_from_gdtype(m_func->get_datatype(), method_doc.return_type, method_doc.return_enum, true);
} else if (!m_func->body->has_return) { } else if (!m_func->body->has_return) {