Documentation: Add support for deprecated/experimental messages

1 files changed, 71 insertions, 5 deletions

diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py
index 76a665d3c0..e52d863f7d 100755
--- a/doc/tools/make_rst.py
+++ b/doc/tools/make_rst.py
@@ -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: