asgardius/virtualx-engine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #91537 from rburing/doc_classref_self_links

Browse source 
Class reference: Add self-links to methods, properties, etc.
This commit is contained in:
Rémi Verschelde 2024-05-28 15:48:34 +02:00
commit 5a13bb56a0
No known key found for this signature in database
GPG key ID: C3336907360768E1
1 changed files with 46 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
doc/tools/make_rst.py
View file

@ -1110,11 +1110,13 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
# Create signal signature and anchor point. # 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") f.write(".. rst-class:: classref-signal\n\n")
_, signature = make_method_signature(class_def, signal, "", state) _, 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. # 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. # 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") f.write(".. rst-class:: classref-enumeration\n\n")
if e.is_bitfield: if e.is_bitfield:
f.write(f"flags **{e.name}**:\n\n") f.write(f"flags **{e.name}**: {self_link}\n\n")
else: 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(): for value in e.values.values():
# Also create signature and anchor point for each enum constant. # 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(): for constant in class_def.constants.values():
# Create constant signature and anchor point. # 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(".. 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. # 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. # Create annotation signature and anchor point.
self_link = ""
if i == 0: 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") f.write(".. rst-class:: classref-annotation\n\n")
_, signature = make_method_signature(class_def, m, "", state) _, 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. # 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. # 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") f.write(".. rst-class:: classref-property\n\n")
property_default = "" property_default = ""
if property_def.default_value is not None: if property_def.default_value is not None:
property_default = f" = {property_def.default_value}" 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. # 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. # Create constructor signature and anchor point.
self_link = ""
if i == 0: 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") f.write(".. rst-class:: classref-constructor\n\n")
ret_type, signature = make_method_signature(class_def, m, "", state) 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. # 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. # Create method signature and anchor point.
self_link = ""
if i == 0: if i == 0:
method_qualifier = "" method_qualifier = ""
if m.name.startswith("_"): if m.name.startswith("_"):
method_qualifier = "private_" method_qualifier = "private_"
method_anchor = f"class_{class_name}_{method_qualifier}method_{m.name}"
f.write(f".. _class_{class_name}_{method_qualifier}method_{m.name}:\n\n") f.write(f".. _{method_anchor}:\n\n")
self_link = f" :ref:`🔗<{method_anchor}>`"
f.write(".. rst-class:: classref-method\n\n") f.write(".. rst-class:: classref-method\n\n")
ret_type, signature = make_method_signature(class_def, m, "", state) 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. # 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. # 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: for parameter in m.parameters:
operator_anchor += f"_{parameter.type_name.type_name}" operator_anchor += f"_{parameter.type_name.type_name}"
operator_anchor += ":\n\n" f.write(f".. _{operator_anchor}:\n\n")
f.write(operator_anchor) self_link = f":ref:`🔗<{operator_anchor}>`"
f.write(".. rst-class:: classref-operator\n\n") f.write(".. rst-class:: classref-operator\n\n")
ret_type, signature = make_method_signature(class_def, m, "", state) 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. # 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. # 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") f.write(".. rst-class:: classref-themeproperty\n\n")
theme_item_default = "" theme_item_default = ""
if theme_item_def.default_value is not None: if theme_item_def.default_value is not None:
theme_item_default = f" = {theme_item_def.default_value}" 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. # Add theme property description, or a call to action if it's missing.