diff options
Diffstat (limited to 'doc/tools/make_rst.py')
| -rwxr-xr-x | doc/tools/make_rst.py | 878 |
1 files changed, 439 insertions, 439 deletions
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 51d67d3456..e10bc3477b 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -889,568 +889,570 @@ 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"), + "w", + encoding="utf-8", + newline="\n", + ) as f: + # Remove the "Edit on Github" button from the online docs page. + f.write(":github_url: hide\n\n") + + # Add keywords metadata. + if class_def.keywords is not None and class_def.keywords != "": + f.write(f".. meta::\n\t:keywords: {class_def.keywords}\n\n") + + # Warn contributors not to edit this file directly. + # Also provide links to the source files for reference. + + git_branch = get_git_branch() + source_xml_path = os.path.relpath(class_def.filepath, root_directory).replace("\\", "/") + source_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/{source_xml_path}" + generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" + + f.write(".. DO NOT EDIT THIS FILE!!!\n") + f.write(".. Generated automatically from Godot engine sources.\n") + f.write(f".. Generator: {generator_github_url}.\n") + 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(make_heading(class_name, "=", False)) + + f.write(make_deprecated_experimental(class_def, state)) + + ### INHERITANCE TREE ### + + # Ascendants + if class_def.inherits: + inherits = class_def.inherits.strip() + f.write(f'**{translate("Inherits:")}** ') + first = True + while inherits in state.classes: + if not first: + f.write(" **<** ") + else: + first = False - if dry_run: - f = open(os.devnull, "w", encoding="utf-8", newline="\n") - else: - f = open(os.path.join(output_dir, f"class_{class_name.lower()}.rst"), "w", encoding="utf-8", newline="\n") - - # Remove the "Edit on Github" button from the online docs page. - f.write(":github_url: hide\n\n") - - # Add keywords metadata. - if class_def.keywords is not None and class_def.keywords != "": - f.write(f".. meta::\n\t:keywords: {class_def.keywords}\n\n") + f.write(make_type(inherits, state)) + inode = state.classes[inherits].inherits + if inode: + inherits = inode.strip() + else: + break + f.write("\n\n") - # Warn contributors not to edit this file directly. - # Also provide links to the source files for reference. + # Descendants + inherited: List[str] = [] + for c in state.classes.values(): + if c.inherits and c.inherits.strip() == class_name: + inherited.append(c.name) + + if len(inherited): + f.write(f'**{translate("Inherited By:")}** ') + for i, child in enumerate(inherited): + if i > 0: + f.write(", ") + f.write(make_type(child, state)) + f.write("\n\n") - git_branch = get_git_branch() - source_xml_path = os.path.relpath(class_def.filepath, root_directory).replace("\\", "/") - source_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/{source_xml_path}" - generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" + ### INTRODUCTION ### - f.write(".. DO NOT EDIT THIS FILE!!!\n") - f.write(".. Generated automatically from Godot engine sources.\n") - f.write(f".. Generator: {generator_github_url}.\n") - f.write(f".. XML source: {source_github_url}.\n\n") + has_description = False - # Document reference id and header. - f.write(f".. _class_{class_name}:\n\n") - f.write(make_heading(class_name, "=", False)) + # Brief description + if class_def.brief_description is not None and class_def.brief_description.strip() != "": + has_description = True - f.write(make_deprecated_experimental(class_def, state)) + f.write(f"{format_text_block(class_def.brief_description.strip(), class_def, state)}\n\n") - ### INHERITANCE TREE ### + # Class description + if class_def.description is not None and class_def.description.strip() != "": + has_description = True - # Ascendants - if class_def.inherits: - inherits = class_def.inherits.strip() - f.write(f'**{translate("Inherits:")}** ') - first = True - while inherits in state.classes: - if not first: - f.write(" **<** ") - else: - first = False + f.write(".. rst-class:: classref-introduction-group\n\n") + f.write(make_heading("Description", "-")) - f.write(make_type(inherits, state)) - inode = state.classes[inherits].inherits - if inode: - inherits = inode.strip() - else: - break - f.write("\n\n") + f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n") - # Descendants - inherited: List[str] = [] - for c in state.classes.values(): - if c.inherits and c.inherits.strip() == class_name: - inherited.append(c.name) + if not has_description: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) - if len(inherited): - f.write(f'**{translate("Inherited By:")}** ') - for i, child in enumerate(inherited): - if i > 0: - f.write(", ") - f.write(make_type(child, state)) - f.write("\n\n") + if class_def.name in CLASSES_WITH_CSHARP_DIFFERENCES: + f.write(".. note::\n\n\t") + f.write( + translate( + "There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information." + ) + + "\n\n" + ) - ### INTRODUCTION ### + # Online tutorials + if len(class_def.tutorials) > 0: + f.write(".. rst-class:: classref-introduction-group\n\n") + f.write(make_heading("Tutorials", "-")) - has_description = False + for url, title in class_def.tutorials: + f.write(f"- {make_link(url, title)}\n\n") - # Brief description - if class_def.brief_description is not None and class_def.brief_description.strip() != "": - has_description = True + ### REFERENCE TABLES ### - f.write(f"{format_text_block(class_def.brief_description.strip(), class_def, state)}\n\n") + # Reused container for reference tables. + ml: List[Tuple[Optional[str], ...]] = [] - # Class description - if class_def.description is not None and class_def.description.strip() != "": - has_description = True + # Properties reference table + if len(class_def.properties) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") + f.write(make_heading("Properties", "-")) - f.write(".. rst-class:: classref-introduction-group\n\n") - f.write(make_heading("Description", "-")) + ml = [] + for property_def in class_def.properties.values(): + 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}>`" + ) + # 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}>`" + ml.append((type_rst, ref, default)) - f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n") + format_table(f, ml, True) - if not has_description: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" - ) - + "\n\n" - ) + # Constructors, Methods, Operators reference tables + if len(class_def.constructors) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") + f.write(make_heading("Constructors", "-")) - if class_def.name in CLASSES_WITH_CSHARP_DIFFERENCES: - f.write(".. note::\n\n\t") - f.write( - translate( - "There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information." - ) - + "\n\n" - ) + ml = [] + for method_list in class_def.constructors.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, "constructor", state)) - # Online tutorials - if len(class_def.tutorials) > 0: - f.write(".. rst-class:: classref-introduction-group\n\n") - f.write(make_heading("Tutorials", "-")) + format_table(f, ml) - for url, title in class_def.tutorials: - f.write(f"- {make_link(url, title)}\n\n") + if len(class_def.methods) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") + f.write(make_heading("Methods", "-")) - ### REFERENCE TABLES ### + ml = [] + for method_list in class_def.methods.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, "method", state)) - # Reused container for reference tables. - ml: List[Tuple[Optional[str], ...]] = [] + format_table(f, ml) - # Properties reference table - if len(class_def.properties) > 0: - f.write(".. rst-class:: classref-reftable-group\n\n") - f.write(make_heading("Properties", "-")) + if len(class_def.operators) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") + f.write(make_heading("Operators", "-")) - ml = [] - for property_def in class_def.properties.values(): - 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}>`" - # 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}>`" - ml.append((type_rst, ref, default)) + ml = [] + for method_list in class_def.operators.values(): + for m in method_list: + ml.append(make_method_signature(class_def, m, "operator", state)) - format_table(f, ml, True) + format_table(f, ml) - # Constructors, Methods, Operators reference tables - if len(class_def.constructors) > 0: - f.write(".. rst-class:: classref-reftable-group\n\n") - f.write(make_heading("Constructors", "-")) + # Theme properties reference table + if len(class_def.theme_items) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") + f.write(make_heading("Theme Properties", "-")) - ml = [] - for method_list in class_def.constructors.values(): - for m in method_list: - ml.append(make_method_signature(class_def, m, "constructor", state)) + 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}>`" + ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) - format_table(f, ml) + format_table(f, ml, True) - if len(class_def.methods) > 0: - f.write(".. rst-class:: classref-reftable-group\n\n") - f.write(make_heading("Methods", "-")) + ### DETAILED DESCRIPTIONS ### - ml = [] - for method_list in class_def.methods.values(): - for m in method_list: - ml.append(make_method_signature(class_def, m, "method", state)) + # Signal descriptions + if len(class_def.signals) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Signals", "-")) - format_table(f, ml) + index = 0 - if len(class_def.operators) > 0: - f.write(".. rst-class:: classref-reftable-group\n\n") - f.write(make_heading("Operators", "-")) + for signal in class_def.signals.values(): + if index != 0: + f.write(make_separator()) - ml = [] - for method_list in class_def.operators.values(): - for m in method_list: - ml.append(make_method_signature(class_def, m, "operator", state)) + # Create signal signature and anchor point. - format_table(f, ml) + f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") + f.write(".. rst-class:: classref-signal\n\n") - # Theme properties reference table - if len(class_def.theme_items) > 0: - f.write(".. rst-class:: classref-reftable-group\n\n") - f.write(make_heading("Theme Properties", "-")) + _, signature = make_method_signature(class_def, signal, "", state) + f.write(f"{signature}\n\n") - 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}>`" - ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) + # Add signal description, or a call to action if it's missing. - format_table(f, ml, True) + f.write(make_deprecated_experimental(signal, state)) - ### DETAILED DESCRIPTIONS ### + if signal.description is not None and signal.description.strip() != "": + f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") + elif signal.deprecated is None and signal.experimental is None: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this signal. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) - # Signal descriptions - if len(class_def.signals) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Signals", "-")) + index += 1 - index = 0 + # Enumeration descriptions + if len(class_def.enums) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Enumerations", "-")) - for signal in class_def.signals.values(): - if index != 0: - f.write(make_separator()) + index = 0 - # Create signal signature and anchor point. + for e in class_def.enums.values(): + if index != 0: + f.write(make_separator()) - f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") - f.write(".. rst-class:: classref-signal\n\n") + # Create enumeration signature and anchor point. - _, signature = make_method_signature(class_def, signal, "", state) - f.write(f"{signature}\n\n") + f.write(f".. _enum_{class_name}_{e.name}:\n\n") + f.write(".. rst-class:: classref-enumeration\n\n") - # Add signal description, or a call to action if it's missing. + if e.is_bitfield: + f.write(f"flags **{e.name}**:\n\n") + else: + f.write(f"enum **{e.name}**:\n\n") - f.write(make_deprecated_experimental(signal, state)) + for value in e.values.values(): + # Also create signature and anchor point for each enum constant. - if signal.description is not None and signal.description.strip() != "": - f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") - elif signal.deprecated is None and signal.experimental is None: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this signal. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" - ) - + "\n\n" - ) + f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") + f.write(".. rst-class:: classref-enumeration-constant\n\n") - index += 1 + f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\n\n") - # Enumeration descriptions - if len(class_def.enums) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Enumerations", "-")) + # Add enum constant description. - index = 0 + f.write(make_deprecated_experimental(value, state)) - for e in class_def.enums.values(): - if index != 0: - f.write(make_separator()) + if value.text is not None and value.text.strip() != "": + f.write(f"{format_text_block(value.text.strip(), value, state)}") + elif value.deprecated is None and value.experimental is None: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) - # Create enumeration signature and anchor point. + f.write("\n\n") - f.write(f".. _enum_{class_name}_{e.name}:\n\n") - f.write(".. rst-class:: classref-enumeration\n\n") + index += 1 - if e.is_bitfield: - f.write(f"flags **{e.name}**:\n\n") - else: - f.write(f"enum **{e.name}**:\n\n") + # Constant descriptions + if len(class_def.constants) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Constants", "-")) - for value in e.values.values(): - # Also create signature and anchor point for each enum constant. + for constant in class_def.constants.values(): + # Create constant signature and anchor point. - f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") - f.write(".. rst-class:: classref-enumeration-constant\n\n") + f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") + f.write(".. rst-class:: classref-constant\n\n") - f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\n\n") + f.write(f"**{constant.name}** = ``{constant.value}``\n\n") - # Add enum constant description. + # Add constant description. - f.write(make_deprecated_experimental(value, state)) + f.write(make_deprecated_experimental(constant, state)) - if value.text is not None and value.text.strip() != "": - f.write(f"{format_text_block(value.text.strip(), value, state)}") - elif value.deprecated is None and value.experimental is None: + if constant.text is not None and constant.text.strip() != "": + f.write(f"{format_text_block(constant.text.strip(), constant, state)}") + elif constant.deprecated is None and constant.experimental is None: f.write(".. container:: contribute\n\n\t") f.write( translate( - "There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + "There is currently no description for this constant. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" ) + "\n\n" ) f.write("\n\n") - index += 1 + # Annotation descriptions + if len(class_def.annotations) > 0: + f.write(make_separator(True)) + f.write(make_heading("Annotations", "-")) - # Constant descriptions - if len(class_def.constants) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Constants", "-")) + index = 0 - for constant in class_def.constants.values(): - # Create constant signature and anchor point. + for method_list in class_def.annotations.values(): # type: ignore + for i, m in enumerate(method_list): + if index != 0: + f.write(make_separator()) - f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") - f.write(".. rst-class:: classref-constant\n\n") + # Create annotation signature and anchor point. - f.write(f"**{constant.name}** = ``{constant.value}``\n\n") + if i == 0: + f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n") - # Add constant description. + f.write(".. rst-class:: classref-annotation\n\n") - f.write(make_deprecated_experimental(constant, state)) + _, signature = make_method_signature(class_def, m, "", state) + f.write(f"{signature}\n\n") - if constant.text is not None and constant.text.strip() != "": - f.write(f"{format_text_block(constant.text.strip(), constant, state)}") - elif constant.deprecated is None and constant.experimental is None: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this constant. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" - ) - + "\n\n" - ) + # Add annotation description, or a call to action if it's missing. - f.write("\n\n") + if m.description is not None and m.description.strip() != "": + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this annotation. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) + + index += 1 - # Annotation descriptions - if len(class_def.annotations) > 0: - f.write(make_separator(True)) - f.write(make_heading("Annotations", "-")) + # Property descriptions + if any(not p.overrides for p in class_def.properties.values()) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Property Descriptions", "-")) - index = 0 + index = 0 + + for property_def in class_def.properties.values(): + if property_def.overrides: + continue - for method_list in class_def.annotations.values(): # type: ignore - for i, m in enumerate(method_list): if index != 0: f.write(make_separator()) - # Create annotation signature and anchor point. + # Create property signature and anchor point. - if i == 0: - f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n") + f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") + f.write(".. rst-class:: classref-property\n\n") - f.write(".. rst-class:: classref-annotation\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") - _, signature = make_method_signature(class_def, m, "", state) - f.write(f"{signature}\n\n") + # Create property setter and getter records. - # Add annotation description, or a call to action if it's missing. + property_setget = "" - if m.description is not None and m.description.strip() != "": - f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") - else: + if property_def.setter is not None and not property_def.setter.startswith("_"): + property_setter = make_setter_signature(class_def, property_def, state) + property_setget += f"- {property_setter}\n" + + if property_def.getter is not None and not property_def.getter.startswith("_"): + property_getter = make_getter_signature(class_def, property_def, state) + property_setget += f"- {property_getter}\n" + + if property_setget != "": + f.write(".. rst-class:: classref-property-setget\n\n") + f.write(property_setget) + f.write("\n") + + # 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") + elif property_def.deprecated is None and property_def.experimental is None: f.write(".. container:: contribute\n\n\t") f.write( translate( - "There is currently no description for this annotation. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + "There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" ) + "\n\n" ) index += 1 - # Property descriptions - if any(not p.overrides for p in class_def.properties.values()) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Property Descriptions", "-")) + # Constructor, Method, Operator descriptions + if len(class_def.constructors) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Constructor Descriptions", "-")) - index = 0 + index = 0 - for property_def in class_def.properties.values(): - if property_def.overrides: - continue + for method_list in class_def.constructors.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write(make_separator()) - if index != 0: - f.write(make_separator()) + # Create constructor signature and anchor point. - # Create property signature and anchor point. + if i == 0: + f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n") - f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") - f.write(".. rst-class:: classref-property\n\n") + f.write(".. rst-class:: classref-constructor\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") + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write(f"{ret_type} {signature}\n\n") - # Create property setter and getter records. + # Add constructor description, or a call to action if it's missing. - property_setget = "" + f.write(make_deprecated_experimental(m, state)) - if property_def.setter is not None and not property_def.setter.startswith("_"): - property_setter = make_setter_signature(class_def, property_def, state) - property_setget += f"- {property_setter}\n" + if m.description is not None and m.description.strip() != "": + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") + elif m.deprecated is None and m.experimental is None: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this constructor. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) - if property_def.getter is not None and not property_def.getter.startswith("_"): - property_getter = make_getter_signature(class_def, property_def, state) - property_setget += f"- {property_getter}\n" + index += 1 - if property_setget != "": - f.write(".. rst-class:: classref-property-setget\n\n") - f.write(property_setget) - f.write("\n") + if len(class_def.methods) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Method Descriptions", "-")) - # Add property description, or a call to action if it's missing. + index = 0 - f.write(make_deprecated_experimental(property_def, state)) + for method_list in class_def.methods.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write(make_separator()) - 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") - elif property_def.deprecated is None and property_def.experimental is None: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" - ) - + "\n\n" - ) + # Create method signature and anchor point. - index += 1 + if i == 0: + method_qualifier = "" + if m.name.startswith("_"): + method_qualifier = "private_" - # Constructor, Method, Operator descriptions - if len(class_def.constructors) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Constructor Descriptions", "-")) + f.write(f".. _class_{class_name}_{method_qualifier}method_{m.name}:\n\n") - index = 0 + f.write(".. rst-class:: classref-method\n\n") - for method_list in class_def.constructors.values(): - for i, m in enumerate(method_list): - if index != 0: - f.write(make_separator()) + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write(f"{ret_type} {signature}\n\n") - # Create constructor signature and anchor point. + # Add method description, or a call to action if it's missing. - if i == 0: - f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n") + f.write(make_deprecated_experimental(m, state)) - 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") - - # 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") - elif m.deprecated is None and m.experimental is None: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this constructor. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + if m.description is not None and m.description.strip() != "": + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") + elif m.deprecated is None and m.experimental is None: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" ) - + "\n\n" - ) - index += 1 - - if len(class_def.methods) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Method Descriptions", "-")) + index += 1 - index = 0 + if len(class_def.operators) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Operator Descriptions", "-")) - for method_list in class_def.methods.values(): - for i, m in enumerate(method_list): - if index != 0: - f.write(make_separator()) + index = 0 - # Create method signature and anchor point. + for method_list in class_def.operators.values(): + for i, m in enumerate(method_list): + if index != 0: + f.write(make_separator()) - if i == 0: - method_qualifier = "" - if m.name.startswith("_"): - method_qualifier = "private_" + # Create operator signature and anchor point. - f.write(f".. _class_{class_name}_{method_qualifier}method_{m.name}:\n\n") + 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 += f":\n\n" + f.write(operator_anchor) - f.write(".. rst-class:: classref-method\n\n") + 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") + ret_type, signature = make_method_signature(class_def, m, "", state) + f.write(f"{ret_type} {signature}\n\n") - # Add method description, or a call to action if it's missing. + # Add operator description, or a call to action if it's missing. - f.write(make_deprecated_experimental(m, state)) + 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") - elif m.deprecated is None and m.experimental is None: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + if m.description is not None and m.description.strip() != "": + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") + elif m.deprecated is None and m.experimental is None: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this operator. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" ) - + "\n\n" - ) - index += 1 + index += 1 - if len(class_def.operators) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Operator Descriptions", "-")) + # Theme property descriptions + if len(class_def.theme_items) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") + f.write(make_heading("Theme Property Descriptions", "-")) - index = 0 + index = 0 - for method_list in class_def.operators.values(): - for i, m in enumerate(method_list): + for theme_item_def in class_def.theme_items.values(): if index != 0: f.write(make_separator()) - # Create operator signature and anchor point. - - 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 += f":\n\n" - f.write(operator_anchor) + # Create theme property signature and anchor point. - f.write(".. rst-class:: classref-operator\n\n") + f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n") + f.write(".. rst-class:: classref-themeproperty\n\n") - ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"{ret_type} {signature}\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") - # Add operator description, or a call to action if it's missing. + # Add theme property description, or a call to action if it's missing. - f.write(make_deprecated_experimental(m, state)) + f.write(make_deprecated_experimental(theme_item_def, state)) - if m.description is not None and m.description.strip() != "": - f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") - elif m.deprecated is None and m.experimental is None: + 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") + elif theme_item_def.deprecated is None and theme_item_def.experimental is None: f.write(".. container:: contribute\n\n\t") f.write( translate( - "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>`!" ) + "\n\n" ) index += 1 - # Theme property descriptions - if len(class_def.theme_items) > 0: - f.write(make_separator(True)) - f.write(".. rst-class:: classref-descriptions-group\n\n") - f.write(make_heading("Theme Property Descriptions", "-")) - - index = 0 - - for theme_item_def in class_def.theme_items.values(): - if index != 0: - f.write(make_separator()) - - # 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") - 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") - - # 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") - elif theme_item_def.deprecated is None and theme_item_def.experimental is None: - f.write(".. container:: contribute\n\n\t") - f.write( - translate( - "There is currently no description for this theme property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" - ) - + "\n\n" - ) - - index += 1 - - f.write(make_footer()) + f.write(make_footer()) def make_type(klass: str, state: State) -> str: @@ -1690,48 +1692,46 @@ def make_link(url: str, title: str) -> str: def make_rst_index(grouped_classes: Dict[str, List[str]], dry_run: bool, output_dir: str) -> None: - if dry_run: - f = open(os.devnull, "w", encoding="utf-8", newline="\n") - else: - f = open(os.path.join(output_dir, "index.rst"), "w", encoding="utf-8", newline="\n") - - # Remove the "Edit on Github" button from the online docs page, and disallow user-contributed notes - # on the index page. User-contributed notes are allowed on individual class pages. - f.write(":github_url: hide\n:allow_comments: False\n\n") + with open( + os.devnull if dry_run else os.path.join(output_dir, "index.rst"), "w", encoding="utf-8", newline="\n" + ) as f: + # Remove the "Edit on Github" button from the online docs page, and disallow user-contributed notes + # on the index page. User-contributed notes are allowed on individual class pages. + f.write(":github_url: hide\n:allow_comments: False\n\n") - # Warn contributors not to edit this file directly. - # Also provide links to the source files for reference. + # Warn contributors not to edit this file directly. + # Also provide links to the source files for reference. - git_branch = get_git_branch() - generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" + git_branch = get_git_branch() + generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" - f.write(".. DO NOT EDIT THIS FILE!!!\n") - f.write(".. Generated automatically from Godot engine sources.\n") - f.write(f".. Generator: {generator_github_url}.\n\n") + f.write(".. DO NOT EDIT THIS FILE!!!\n") + f.write(".. Generated automatically from Godot engine sources.\n") + f.write(f".. Generator: {generator_github_url}.\n\n") - f.write(".. _doc_class_reference:\n\n") + f.write(".. _doc_class_reference:\n\n") - f.write(make_heading("All classes", "=")) + f.write(make_heading("All classes", "=")) - for group_name in CLASS_GROUPS: - if group_name in grouped_classes: - f.write(make_heading(CLASS_GROUPS[group_name], "=")) + for group_name in CLASS_GROUPS: + if group_name in grouped_classes: + f.write(make_heading(CLASS_GROUPS[group_name], "=")) - f.write(".. toctree::\n") - f.write(" :maxdepth: 1\n") - f.write(f" :name: toc-class-ref-{group_name}s\n") - f.write("\n") + f.write(".. toctree::\n") + f.write(" :maxdepth: 1\n") + f.write(f" :name: toc-class-ref-{group_name}s\n") + f.write("\n") - if group_name in CLASS_GROUPS_BASE: - f.write(f" class_{CLASS_GROUPS_BASE[group_name].lower()}\n") + if group_name in CLASS_GROUPS_BASE: + f.write(f" class_{CLASS_GROUPS_BASE[group_name].lower()}\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(): - continue + 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(): + continue - f.write(f" class_{class_name.lower()}\n") + f.write(f" class_{class_name.lower()}\n") - f.write("\n") + f.write("\n") # Formatting helpers. |