mirror of
https://github.com/godotengine/godot.git
synced 2025-10-19 16:03:29 +00:00
Adjust make_rst.py for GDScript documentation
This commit is contained in:
Danil Alexeev
parent
0eadbdb5d0
commit
ba943e4481
2 changed files with 45 additions and 31 deletions
|
|
@ -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 ", "")
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue