Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adjust make_rst.py for GDScript documentation #98533

Merged
merged 1 commit into from
Dec 2, 2024
Merged

Adjust make_rst.py for GDScript documentation #98533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 39 additions & 28 deletions doc/tools/make_rst.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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))
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand All @@ -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")
Expand Down Expand Up @@ -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")
Expand All @@ -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")
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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}>`"

Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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}>`"

Expand Down Expand Up @@ -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}>`"

Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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}``"
Expand All @@ -1533,7 +1535,7 @@ def resolve_type(link_type: str) -> 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 :]
Expand All @@ -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)

Expand All @@ -1576,17 +1578,17 @@ 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 += ">`"
elif ref_type == "method":
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}**"

Expand Down Expand Up @@ -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")

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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("/", "--")
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Borrowed from here:

godot/editor/doc_tools.cpp

Line 1612 in 61accf0

String save_file = save_path.path_join(c.name.replace("\"", "").replace("/", "--") + ".xml");

else:
return dirty_name.replace('"', "").replace("/", "_").replace(".", "_")


def sanitize_operator_name(dirty_name: str, state: State) -> str:
clear_name = dirty_name.replace("operator ", "")

Expand Down
9 changes: 6 additions & 3 deletions modules/gdscript/editor/gdscript_docgen.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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) {
Expand Down
Loading