From bba3c707221f90bf294b964c938d4e704a53d58b Mon Sep 17 00:00:00 2001 From: Yuri Sizov Date: Mon, 15 Jan 2024 14:08:35 +0100 Subject: [PATCH] Add code sample language parity check to make_rst.py --- doc/tools/make_rst.py | 169 ++++++++++++++++++++++++++++++------------ 1 file changed, 122 insertions(+), 47 deletions(-) diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index df3e92853825..9b4f7c8b6d1d 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -141,6 +141,9 @@ class State: self.classes: OrderedDict[str, ClassDef] = OrderedDict() self.current_class: str = "" + # Additional content and structure checks and validators. + self.script_language_parity_check: ScriptLanguageParityCheck = ScriptLanguageParityCheck() + def parse_class(self, class_root: ET.Element, filepath: str) -> None: class_name = class_root.attrib["name"] self.current_class = class_name @@ -543,6 +546,9 @@ class ClassDef(DefinitionBase): def __init__(self, name: str) -> None: super().__init__("class", name) + self.class_group = "variant" + self.editor_class = self._is_editor_class() + self.constants: OrderedDict[str, ConstantDef] = OrderedDict() self.enums: OrderedDict[str, EnumDef] = OrderedDict() self.properties: OrderedDict[str, PropertyDef] = OrderedDict() @@ -560,6 +566,65 @@ class ClassDef(DefinitionBase): # Used to match the class with XML source for output filtering purposes. self.filepath: str = "" + def _is_editor_class(self) -> bool: + if self.name.startswith("Editor"): + return True + if self.name in EDITOR_CLASSES: + return True + + return False + + def update_class_group(self, state: State) -> None: + group_name = "variant" + + if self.name.startswith("@"): + group_name = "global" + elif self.inherits: + inherits = self.inherits.strip() + + while inherits in state.classes: + if inherits == "Node": + group_name = "node" + break + if inherits == "Resource": + group_name = "resource" + break + if inherits == "Object": + group_name = "object" + break + + inode = state.classes[inherits].inherits + if inode: + inherits = inode.strip() + else: + break + + self.class_group = group_name + + +# Checks if code samples have both GDScript and C# variations. +# For simplicity we assume that a GDScript example is always present, and ignore contexts +# which don't necessarily need C# examples. +class ScriptLanguageParityCheck: + def __init__(self) -> None: + self.hit_map: OrderedDict[str, List[Tuple[DefinitionBase, str]]] = OrderedDict() + self.hit_count = 0 + + def add_hit(self, class_name: str, context: DefinitionBase, error: str, state: State) -> None: + if class_name in ["@GDScript", "@GlobalScope"]: + return # We don't expect these contexts to have parity. + + class_def = state.classes[class_name] + if class_def.class_group == "variant" and class_def.name != "Object": + return # Variant types are replaced with native types in C#, we don't expect parity. + + self.hit_count += 1 + + if class_name not in self.hit_map: + self.hit_map[class_name] = [] + + self.hit_map[class_name].append((context, error)) + # Entry point for the RST generator. def main() -> None: @@ -590,6 +655,11 @@ def main() -> None: action="store_true", help="If passed, no output will be generated and XML files are only checked for errors.", ) + parser.add_argument( + "--verbose", + action="store_true", + help="If passed, enables verbose printing.", + ) args = parser.parse_args() should_color = args.color or (hasattr(sys.stdout, "isatty") and sys.stdout.isatty()) @@ -684,15 +754,15 @@ def main() -> None: if args.filter and not pattern.search(class_def.filepath): continue state.current_class = class_name + + class_def.update_class_group(state) make_rst_class(class_def, state, args.dry_run, args.output) - group_name = get_class_group(class_def, state) + if class_def.class_group not in grouped_classes: + grouped_classes[class_def.class_group] = [] + grouped_classes[class_def.class_group].append(class_name) - if group_name not in grouped_classes: - grouped_classes[group_name] = [] - grouped_classes[group_name].append(class_name) - - if is_editor_class(class_def): + if class_def.editor_class: if "editor" not in grouped_classes: grouped_classes["editor"] = [] grouped_classes["editor"].append(class_name) @@ -704,6 +774,26 @@ def main() -> None: print("") + # Print out checks. + + if state.script_language_parity_check.hit_count > 0: + if not args.verbose: + print( + f'{STYLES["yellow"]}{state.script_language_parity_check.hit_count} code samples failed parity check. Use --verbose to get more information.{STYLES["reset"]}' + ) + else: + print( + f'{STYLES["yellow"]}{state.script_language_parity_check.hit_count} code samples failed parity check:{STYLES["reset"]}' + ) + + for class_name in state.script_language_parity_check.hit_map.keys(): + class_hits = state.script_language_parity_check.hit_map[class_name] + print(f'{STYLES["yellow"]}- {len(class_hits)} hits in class "{class_name}"{STYLES["reset"]}') + + for context, error in class_hits: + print(f" - {error} in {format_context_name(context)}") + print("") + # Print out warnings and errors, or lack thereof, and exit with an appropriate code. if state.num_warnings >= 2: @@ -760,46 +850,6 @@ def get_git_branch() -> str: return "master" -def get_class_group(class_def: ClassDef, state: State) -> str: - group_name = "variant" - class_name = class_def.name - - if class_name.startswith("@"): - group_name = "global" - elif class_def.inherits: - inherits = class_def.inherits.strip() - - while inherits in state.classes: - if inherits == "Node": - group_name = "node" - break - if inherits == "Resource": - group_name = "resource" - break - if inherits == "Object": - group_name = "object" - break - - inode = state.classes[inherits].inherits - if inode: - inherits = inode.strip() - else: - break - - return group_name - - -def is_editor_class(class_def: ClassDef) -> bool: - class_name = class_def.name - - if class_name.startswith("Editor"): - return True - if class_name in EDITOR_CLASSES: - return True - - return False - - # Generator methods. @@ -1642,7 +1692,7 @@ def parse_link_target(link_target: str, state: State, context_name: str) -> List def format_text_block( text: str, - context: Union[DefinitionBase, None], + context: DefinitionBase, state: State, ) -> str: # Linebreak + tabs in the XML should become two line breaks unless in a "codeblock" @@ -1692,6 +1742,9 @@ def format_text_block( inside_code_tabs = False ignore_code_warnings = False + has_codeblocks_gdscript = False + has_codeblocks_csharp = False + pos = 0 tag_depth = 0 while True: @@ -1759,6 +1812,17 @@ def format_text_block( elif tag_state.name == "codeblocks": if tag_state.closing: + if not has_codeblocks_gdscript or not has_codeblocks_csharp: + state.script_language_parity_check.add_hit( + state.current_class, + context, + "Only one script language sample found in [codeblocks]", + state, + ) + + has_codeblocks_gdscript = False + has_codeblocks_csharp = False + tag_depth -= 1 tag_text = "" inside_code_tabs = False @@ -1776,6 +1840,8 @@ def format_text_block( f"{state.current_class}.xml: GDScript code block is used outside of [codeblocks] in {context_name}.", state, ) + else: + has_codeblocks_gdscript = True tag_text = "\n .. code-tab:: gdscript\n" elif tag_state.name == "csharp": if not inside_code_tabs: @@ -1783,8 +1849,17 @@ def format_text_block( f"{state.current_class}.xml: C# code block is used outside of [codeblocks] in {context_name}.", state, ) + else: + has_codeblocks_csharp = True tag_text = "\n .. code-tab:: csharp\n" else: + state.script_language_parity_check.add_hit( + state.current_class, + context, + "Code sample is formatted with [codeblock] where [codeblocks] should be used", + state, + ) + tag_text = "\n::\n" inside_code = True