From b280bc0d7f9473ef975655c04a68303e22154fc2 Mon Sep 17 00:00:00 2001 From: Ricardo Buring Date: Fri, 3 May 2024 22:29:01 +0200 Subject: [PATCH] Class reference: Add self-links to methods, properties, etc. --- doc/tools/make_rst.py | 68 +++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 22 deletions(-) diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index bc379f85535..761a7f8f4a1 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -1110,11 +1110,13 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create signal signature and anchor point. - f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") + signal_anchor = f"class_{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") _, signature = make_method_signature(class_def, signal, "", state) - f.write(f"{signature}\n\n") + f.write(f"{signature} {self_link}\n\n") # Add signal description, or a call to action if it's missing. @@ -1147,13 +1149,15 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create enumeration signature and anchor point. - f.write(f".. _enum_{class_name}_{e.name}:\n\n") + enum_anchor = f"enum_{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") if e.is_bitfield: - f.write(f"flags **{e.name}**:\n\n") + f.write(f"flags **{e.name}**: {self_link}\n\n") else: - f.write(f"enum **{e.name}**:\n\n") + f.write(f"enum **{e.name}**: {self_link}\n\n") for value in e.values.values(): # Also create signature and anchor point for each enum constant. @@ -1191,10 +1195,12 @@ 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. - f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") + constant_anchor = f"class_{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") - f.write(f"**{constant.name}** = ``{constant.value}``\n\n") + f.write(f"**{constant.name}** = ``{constant.value}`` {self_link}\n\n") # Add constant description. @@ -1227,13 +1233,16 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create annotation signature and anchor point. + self_link = "" if i == 0: - f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n") + annotation_anchor = f"class_{class_name}_annotation_{m.name}" + f.write(f".. _{annotation_anchor}:\n\n") + self_link = f" :ref:`🔗<{annotation_anchor}>`" f.write(".. rst-class:: classref-annotation\n\n") _, signature = make_method_signature(class_def, m, "", state) - f.write(f"{signature}\n\n") + f.write(f"{signature}{self_link}\n\n") # Add annotation description, or a call to action if it's missing. @@ -1267,13 +1276,17 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create property signature and anchor point. - f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") + property_anchor = f"class_{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") property_default = "" if property_def.default_value is not None: property_default = f" = {property_def.default_value}" - f.write(f"{property_def.type_name.to_rst(state)} **{property_def.name}**{property_default}\n\n") + f.write( + f"{property_def.type_name.to_rst(state)} **{property_def.name}**{property_default} {self_link}\n\n" + ) # Create property setter and getter records. @@ -1327,13 +1340,16 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create constructor signature and anchor point. + self_link = "" if i == 0: - f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n") + constructor_anchor = f"class_{class_name}_constructor_{m.name}" + f.write(f".. _{constructor_anchor}:\n\n") + self_link = f" :ref:`🔗<{constructor_anchor}>`" f.write(".. rst-class:: classref-constructor\n\n") ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"{ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}{self_link}\n\n") # Add constructor description, or a call to action if it's missing. @@ -1366,17 +1382,21 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create method signature and anchor point. + self_link = "" + if i == 0: method_qualifier = "" if m.name.startswith("_"): method_qualifier = "private_" - - f.write(f".. _class_{class_name}_{method_qualifier}method_{m.name}:\n\n") + method_anchor = f"class_{class_name}_{method_qualifier}method_{m.name}" + f.write(f".. _{method_anchor}:\n\n") + self_link = f" :ref:`🔗<{method_anchor}>`" f.write(".. rst-class:: classref-method\n\n") ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"{ret_type} {signature}\n\n") + + f.write(f"{ret_type} {signature}{self_link}\n\n") # Add method description, or a call to action if it's missing. @@ -1409,16 +1429,16 @@ 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_{class_name}_operator_{sanitize_operator_name(m.name, state)}" for parameter in m.parameters: operator_anchor += f"_{parameter.type_name.type_name}" - operator_anchor += ":\n\n" - f.write(operator_anchor) + f.write(f".. _{operator_anchor}:\n\n") + self_link = f":ref:`🔗<{operator_anchor}>`" f.write(".. rst-class:: classref-operator\n\n") ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"{ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature} {self_link}\n\n") # Add operator description, or a call to action if it's missing. @@ -1451,13 +1471,17 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Create theme property signature and anchor point. - f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n") + theme_item_anchor = f"class_{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") theme_item_default = "" if theme_item_def.default_value is not None: theme_item_default = f" = {theme_item_def.default_value}" - f.write(f"{theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**{theme_item_default}\n\n") + f.write( + f"{theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**{theme_item_default} {self_link}\n\n" + ) # Add theme property description, or a call to action if it's missing.