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

Documentation: Add support for deprecated/experimental messages

Browse Source
This commit is contained in:
Danil Alexeev
2024-02-12 16:55:02 +03:00
parent 907db8eebc
commit af28f87791
75 changed files with 1165 additions and 738 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
doc/tools/make_rst.py
View File

@@ -77,6 +77,15 @@ BASE_STRINGS = [
"There is currently no description for this operator. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
"There is currently no description for this theme property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
"There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information.",
"Deprecated:",
"Experimental:",
"This signal may be changed or removed in future versions.",
"This constant may be changed or removed in future versions.",
"This property may be changed or removed in future versions.",
"This constructor may be changed or removed in future versions.",
"This method may be changed or removed in future versions.",
"This operator may be changed or removed in future versions.",
"This theme property may be changed or removed in future versions.",
]
strings_l10n: Dict[str, str] = {}
@@ -158,6 +167,9 @@ class State:
if inherits is not None:
class_def.inherits = inherits
class_def.deprecated = class_root.get("deprecated")
class_def.experimental = class_root.get("experimental")
brief_desc = class_root.find("brief_description")
if brief_desc is not None and brief_desc.text:
class_def.brief_description = brief_desc.text
@@ -191,6 +203,8 @@ class State:
property_def = PropertyDef(
property_name, type_name, setter, getter, property.text, default_value, overrides
)
property_def.deprecated = property.get("deprecated")
property_def.experimental = property.get("experimental")
class_def.properties[property_name] = property_def
constructors = class_root.find("constructors")
@@ -216,6 +230,8 @@ class State:
method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers)
method_def.definition_name = "constructor"
method_def.deprecated = constructor.get("deprecated")
method_def.experimental = constructor.get("experimental")
if method_name not in class_def.constructors:
class_def.constructors[method_name] = []
@@ -244,6 +260,8 @@ class State:
method_desc = desc_element.text
method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers)
method_def.deprecated = method.get("deprecated")
method_def.experimental = method.get("experimental")
if method_name not in class_def.methods:
class_def.methods[method_name] = []
@@ -273,6 +291,8 @@ class State:
method_def = MethodDef(method_name, return_type, params, method_desc, qualifiers)
method_def.definition_name = "operator"
method_def.deprecated = operator.get("deprecated")
method_def.experimental = operator.get("experimental")
if method_name not in class_def.operators:
class_def.operators[method_name] = []
@@ -288,6 +308,8 @@ class State:
enum = constant.get("enum")
is_bitfield = constant.get("is_bitfield") == "true"
constant_def = ConstantDef(constant_name, value, constant.text, is_bitfield)
constant_def.deprecated = constant.get("deprecated")
constant_def.experimental = constant.get("experimental")
if enum is None:
if constant_name in class_def.constants:
print_error(f'{class_name}.xml: Duplicate constant "{constant_name}".', self)
@@ -345,6 +367,8 @@ class State:
signal_desc = desc_element.text
signal_def = SignalDef(signal_name, params, signal_desc)
signal_def.deprecated = signal.get("deprecated")
signal_def.experimental = signal.get("experimental")
class_def.signals[signal_name] = signal_def
theme_items = class_root.find("theme_items")
@@ -357,7 +381,7 @@ class State:
theme_item_id = "{}_{}".format(theme_item_data_name, theme_item_name)
if theme_item_id in class_def.theme_items:
print_error(
f'{class_name}.xml: Duplicate theme item "{theme_item_name}" of type "{theme_item_data_name}".',
f'{class_name}.xml: Duplicate theme property "{theme_item_name}" of type "{theme_item_data_name}".',
self,
)
continue
@@ -447,6 +471,8 @@ class DefinitionBase:
) -> None:
self.definition_name = definition_name
self.name = name
self.deprecated: Optional[str] = None
self.experimental: Optional[str] = None
class PropertyDef(DefinitionBase):
@@ -540,7 +566,7 @@ class ThemeItemDef(DefinitionBase):
def __init__(
self, name: str, type_name: TypeName, data_name: str, text: Optional[str], default_value: Optional[str]
) -> None:
super().__init__("theme item", name)
super().__init__("theme property", name)
self.type_name = type_name
self.data_name = data_name
@@ -892,6 +918,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
f.write(f".. _class_{class_name}:\n\n")
f.write(make_heading(class_name, "=", False))
f.write(make_deprecated_experimental(class_def, state))
### INHERITANCE TREE ###
# Ascendants
@@ -1066,6 +1094,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add signal description, or a call to action if it's missing.
f.write(make_deprecated_experimental(signal, state))
if signal.description is not None and signal.description.strip() != "":
f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n")
else:
@@ -1111,6 +1141,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add enum constant description.
f.write(make_deprecated_experimental(value, state))
if value.text is not None and value.text.strip() != "":
f.write(f"{format_text_block(value.text.strip(), value, state)}")
else:
@@ -1140,7 +1172,9 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
f.write(f"**{constant.name}** = ``{constant.value}``\n\n")
# Add enum constant description.
# Add constant description.
f.write(make_deprecated_experimental(constant, state))
if constant.text is not None and constant.text.strip() != "":
f.write(f"{format_text_block(constant.text.strip(), constant, state)}")
@@ -1236,6 +1270,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add property description, or a call to action if it's missing.
f.write(make_deprecated_experimental(property_def, state))
if property_def.text is not None and property_def.text.strip() != "":
f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n")
else:
@@ -1274,6 +1310,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add constructor description, or a call to action if it's missing.
f.write(make_deprecated_experimental(m, state))
if m.description is not None and m.description.strip() != "":
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
else:
@@ -1315,6 +1353,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add method description, or a call to action if it's missing.
f.write(make_deprecated_experimental(m, state))
if m.description is not None and m.description.strip() != "":
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
else:
@@ -1355,6 +1395,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add operator description, or a call to action if it's missing.
f.write(make_deprecated_experimental(m, state))
if m.description is not None and m.description.strip() != "":
f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
else:
@@ -1392,6 +1434,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Add theme property description, or a call to action if it's missing.
f.write(make_deprecated_experimental(theme_item_def, state))
if theme_item_def.text is not None and theme_item_def.text.strip() != "":
f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n")
else:
@@ -1542,6 +1586,28 @@ def make_getter_signature(class_def: ClassDef, property_def: PropertyDef, state:
return f"{ret_type} {signature}"
def make_deprecated_experimental(item: DefinitionBase, state: State) -> str:
result = ""
if item.deprecated is not None:
deprecated_prefix = translate("Deprecated:")
if item.deprecated.strip() == "":
default_message = translate(f"This {item.definition_name} may be changed or removed in future versions.")
result += f"**{deprecated_prefix}** {default_message}\n\n"
else:
result += f"**{deprecated_prefix}** {format_text_block(item.deprecated.strip(), item, state)}\n\n"
if item.experimental is not None:
experimental_prefix = translate("Experimental:")
if item.experimental.strip() == "":
default_message = translate(f"This {item.definition_name} may be changed or removed in future versions.")
result += f"**{experimental_prefix}** {default_message}\n\n"
else:
result += f"**{experimental_prefix}** {format_text_block(item.experimental.strip(), item, state)}\n\n"
return result
def make_heading(title: str, underline: str, l10n: bool = True) -> str:
if l10n:
new_title = translate(title)
@@ -1965,7 +2031,7 @@ def format_text_block(
elif target_name in class_def.theme_items:
print_warning(
f'{state.current_class}.xml: Found a code string "{inside_code_text}" that matches the {target_class_name}.{target_name} theme item in {context_name}. {code_warning_if_intended_string}',
f'{state.current_class}.xml: Found a code string "{inside_code_text}" that matches the {target_class_name}.{target_name} theme property in {context_name}. {code_warning_if_intended_string}',
state,
)
@@ -2076,7 +2142,7 @@ def format_text_block(
elif tag_state.name == "theme_item":
if target_name not in class_def.theme_items:
print_error(
f'{state.current_class}.xml: Unresolved theme item reference "{link_target}" in {context_name}.',
f'{state.current_class}.xml: Unresolved theme property reference "{link_target}" in {context_name}.',
state,
)
else: