Formating & Linting & Comments

Author: MaximilianSoerenPollak

scripts_bazel/generate_sourcelinks_cli.py

@@ -35,6 +35,22 @@
 logger = logging.getLogger(__name__)
 
 
+def clean_external_prefix(path: Path) -> Path:
+    """
+    As it can be in combo builds that the path is:
+    `external/score_docs_as_code+/....` or similar
+    We have to remove this prefix from the file
+    before we pass it to the extract function. Otherwise we have
+    this prefix inside the `file` attribute leading to wrong links
+    """
+    if not str(path).startswith("external/"):
+        return path
+    # This allows for files / folders etc. to have `external` in their name too.
+    path_raw = str(path).removeprefix("external/")
+    filepath_split = str(path_raw).split("/", maxsplit=1)
+    return Path("".join(filepath_split[1:]))
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Generate source code links JSON from source files"
@@ -67,8 +83,9 @@ def main():
             metadata_set = True
         abs_file_path = file_path.resolve()
         assert abs_file_path.exists(), abs_file_path
+        clean_path = clean_external_prefix(file_path)
         references = _extract_references_from_file(
-            abs_file_path.parent, Path(abs_file_path.name), file_path
+            abs_file_path.parent, Path(abs_file_path.name), clean_path
         )
         all_need_references.extend(references)
     store_source_code_links_with_metadata_json(

scripts_bazel/merge_sourcelinks.py

@@ -27,20 +27,13 @@
 logger = logging.getLogger(__name__)
 
 
-
 """
 if bazel-out/k8-fastbuild/bin/external/ in file_path => module is external
 otherwise it's local
 if local => module_name & hash == empty
 if external => parse thing for module_name => look up known_good json for hash & url
 """
 
-
-
-def add_needid_to_metaneed_mapping(mapping: dict[str, dict[str, str]], metadata: dict[str, str], needid: str):
-    mapping
-    pass
-
 def main():
     parser = argparse.ArgumentParser(
         description="Merge multiple sourcelinks JSON files into one"
@@ -67,7 +60,6 @@ def main():
     all_files = [x for x in args.files if "known_good.json" not in str(x)]
 
     merged = []
-    needs_metadata_mapping = {}
     for json_file in all_files:
         with open(json_file) as f:
             data = json.load(f)

src/extensions/score_source_code_linker/generate_source_code_links_json.py

@@ -50,7 +50,13 @@ def _extract_references_from_line(line: str):
 def _extract_references_from_file(
     root: Path, file_path_name: Path, file_path: Path
 ) -> list[NeedLink]:
-    """Scan a single file for template strings and return findings."""
+    """Scan a single file for template strings and return findings.
+    Examples:
+    # ROOT: <local_root>/docs-as-code/src/extensions/score_source_code_linker
+    #FILE PATH:
+        external/score_docs_as_code+/src/extensions/score_source_code_linker/testlink.py
+    #FILE PATH NAME:  testlink.py
+    """
     assert root.is_absolute(), "Root path must be absolute"
     assert not file_path_name.is_absolute(), "File path must be relative to the root"
     # assert file_path.is_relative_to(root), (

src/extensions/score_source_code_linker/xml_parser.py

@@ -54,6 +54,23 @@
 
 
 def get_metadata_from_test_path(filepath: Path) -> MetaData:
+    """
+    Will parse out the metadata from the testpath.
+    If test is local then the metadata will be:
+
+        "module_name": "local_module",
+        "hash": "",
+        "url": "",
+
+    Else it will parse the module_name e.g. `score_docs_as_code`
+    match this in the known_good_json and grab the accompanying
+    hash, url as well and return metadata like so for example:
+
+          "module_name": "score_docs_as_code",
+          "hash": "c1207676afe6cafd25c35d420e73279a799515d8",
+          "url": "https://github.com/eclipse-score/docs-as-code"
+
+    """
     known_good_json = os.environ.get("KNOWN_GOOD_JSON")
     module_name = parse_module_name_from_path(filepath)
     md: MetaData = {
@@ -193,13 +210,17 @@ def read_test_xml_file(file: Path) -> tuple[list[DataOfTestCase], list[str], lis
     return test_case_needs, non_prop_tests, missing_prop_tests
 
 
-# /home/maximilianp/score_personal/reference_integration/bazel-testlogs/external/score_docs_as_code+/src/helper_lib/helper_lib_tests/test.xml
 def find_xml_files(dir: Path) -> list[Path]:
     """
     Recursively search all test.xml files inside 'bazel-testlogs'
 
     Returns:
         - list[Path] => Paths to all found 'test.xml' files.
+
+    Example combo TestPath for future reference:
+
+    '<local path to folder>/reference_integration/bazel-testlogs
+    /feature_integration_tests/test_cases/fit/test.xml'
     """
 
     test_file_name = "test.xml"
@@ -208,21 +229,19 @@ def find_xml_files(dir: Path) -> list[Path]:
     for root, _, files in os.walk(dir):
         if test_file_name in files:
             xml_paths.append(Path(os.path.join(root, test_file_name)))
-    print("=========================================")
-    print(xml_paths[0])
-    print("=========================================")
+
     return xml_paths
 
 
-def find_test_folder(base_path: Path | None = None) -> tuple[Path | None, Path | None]:
+def find_test_folder(base_path: Path | None = None) -> Path | None:
     ws_root = base_path if base_path is not None else find_ws_root()
     assert ws_root is not None
     if os.path.isdir(ws_root / "tests-report"):
-        return ws_root, ws_root / "tests-report"
+        return ws_root / "tests-report"
     if os.path.isdir(ws_root / "bazel-testlogs"):
-        return ws_root, ws_root / "bazel-testlogs"
+        return ws_root / "bazel-testlogs"
     logger.info("could not find tests-report or bazel-testlogs to parse testcases")
-    return ws_root, None
+    return None
 
 
 def run_xml_parser(app: Sphinx, env: BuildEnvironment):
@@ -231,19 +250,10 @@ def run_xml_parser(app: Sphinx, env: BuildEnvironment):
     building testcase needs.
     It gets called from the source_code_linker __init__
     """
-    root_path, testlogs_dir = find_test_folder()
-    # early return
+    testlogs_dir = find_test_folder()
     if testlogs_dir is None:
         return
     xml_file_paths = find_xml_files(testlogs_dir)
-    # scl_with_metadata = load_source_code_links_with_metadata_json(
-    #     app.outdir / "score_source_links_metadata.json"
-    # )[0]
-    # metadata: MetaData = {
-    #     "module_name": scl_with_metadata.module_name,
-    #     "hash": scl_with_metadata.hash,
-    #     "url": scl_with_metadata.url,
-    # }
     test_case_needs = build_test_needs_from_files(app, env, xml_file_paths)
     # Saving the test case needs for cache
     store_data_of_test_case_json(
@@ -301,6 +311,7 @@ def construct_and_add_need(app: Sphinx, tn: DataOfTestCase):
     assert tn.module_name is not None
     assert tn.hash is not None
     assert tn.url is not None
+    # Have to build metadata here for the gh link func
     metadata = ModuleInfo(name=tn.module_name, hash=tn.hash, url=tn.url)
     # IDK if this is ideal or not
     with contextlib.suppress(BaseException):