improve warning handling and docs string

Author: juiwenchen

src/sphinx_codelinks/analyse/analyse.py

@@ -3,7 +3,7 @@
 import json
 import logging
 from pathlib import Path
-from typing import Any, TypedDict
+from typing import Any, TypedDict, cast
 
 from lark import UnexpectedInput
 from tree_sitter import Node as TreeSitterNode
@@ -56,6 +56,8 @@ class AnalyseWarning:
 
 
 class SourceAnalyse:
+    """Analyse source files from a single project."""
+
     def __init__(
         self,
         analyse_config: SourceAnalyseConfig,
@@ -427,6 +429,11 @@ def extract_marked_content(self) -> None:
             logger.info(f"Oneline needs extracted: {len(self.oneline_needs)}")
         if self.analyse_config.get_rst:
             logger.info(f"Marked rst extracted: {len(self.marked_rst)}")
+            cnt_resolved = 0
+            for rst in self.marked_rst:
+                if rst.need:
+                    cnt_resolved += 1
+            logger.info(f"Marked rst valid to need: {cnt_resolved}")
 
     def merge_marked_content(self) -> None:
         self.all_marked_content.extend(self.need_id_refs)
@@ -438,6 +445,10 @@ def merge_marked_content(self) -> None:
         )
 
     def dump_marked_content(self, outdir: Path) -> None:
+        """Dump marked content to the given output directory.
+
+        This function is mainly for API users who want to dump marked content separately.
+        """
         output_path = outdir / "marked_content.json"
         if not output_path.parent.exists():
             output_path.parent.mkdir(parents=True)
@@ -448,6 +459,25 @@ def dump_marked_content(self, outdir: Path) -> None:
             json.dump(to_dump, f)
         logger.info(f"Marked content dumped to {output_path}")
 
+    def dump_warnings(self, outdir: Path) -> None:
+        """Dump warnings to the given output directory.
+
+        This function is mainly for API users who want to dump warnings separately.
+        """
+        output_path = outdir / "analyse_warnings.json"
+        if not output_path.parent.exists():
+            output_path.parent.mkdir(parents=True)
+        current_warnings: list[AnalyseWarningType] = [
+            cast(AnalyseWarningType, _warning.__dict__)
+            for _warning in list(self.rst_warnings) + list(self.oneline_warnings)
+        ]
+        with output_path.open("w") as f:
+            json.dump(
+                current_warnings,
+                f,
+            )
+        logger.info(f"Warnings dumped to {output_path}")
+
     def run(self) -> None:
         self.create_src_objects()
         self.extract_marked_content()

src/sphinx_codelinks/analyse/projects.py

@@ -20,6 +20,11 @@
 
 
 class AnalyseProjects:
+    """Analyse multiple projects based on the given CodeLinksConfig.
+
+    This class uses SourceAnalyse for each project defined in the CodeLinksConfig.
+    """
+
     warning_filepath: Path = Path("warnings") / "codelinks_warnings.json"
 
     def __init__(self, codelink_config: CodeLinksConfig) -> None:
@@ -67,18 +72,25 @@ def load_warnings(cls, warnings_dir: Path) -> list[AnalyseWarning] | None:
         return loaded_warnings
 
     def update_warnings(self) -> None:
+        """Update and dump warnings from all projects' analyses."""
         current_warnings: list[AnalyseWarningType] = [
             cast(AnalyseWarningType, _warning.__dict__)
             for analyse in self.projects_analyse.values()
-            for _warning in analyse.oneline_warnings
+            for _warning in list(analyse.rst_warnings) + list(analyse.oneline_warnings)
         ]
+
+        if not current_warnings:
+            logger.info("No warnings to dump.")
+            return
         self.dump_warnings(current_warnings)
 
     def dump_warnings(self, warnings: list[AnalyseWarningType]) -> None:
+        """Dump warnings to the configured warnings path."""
         if not self.warnings_path.parent.exists():
             self.warnings_path.parent.mkdir(parents=True)
         with self.warnings_path.open("w") as f:
             json.dump(
                 warnings,
                 f,
             )
+        logger.info(f"Warnings dumped to {self.warnings_path}")

src/sphinx_codelinks/cmd.py

@@ -151,6 +151,7 @@ def analyse(
     analyse_projects = AnalyseProjects(codelinks_config)
     analyse_projects.run()
     analyse_projects.dump_markers()
+    analyse_projects.update_warnings()
 
 
 @app.command(no_args_is_help=True)

tests/__snapshots__/test_analyse/test_analyse_rst[warning_invalid_type].anchors.json

@@ -0,0 +1,47 @@
+[
+  {
+    "filepath": "dummy_1.c",
+    "remote_url": null,
+    "source_map": {
+      "start": {
+        "row": 2,
+        "column": 0
+      },
+      "end": {
+        "row": 6,
+        "column": 59
+      }
+    },
+    "tagged_scope": "int main() {\n  return 0;\n}",
+    "rst": " .. imp@:: implement main function\n    :id: REQ_001\n    :links: IMPL_001, IMPL_002\n\n    This is content for the main function implementation.\n ",
+    "need": null,
+    "type": "rst"
+  },
+  {
+    "filepath": "dummy_1.c",
+    "remote_url": null,
+    "source_map": {
+      "start": {
+        "row": 14,
+        "column": 0
+      },
+      "end": {
+        "row": 18,
+        "column": 59
+      }
+    },
+    "tagged_scope": "int func1() {\n  return 0;\n}",
+    "rst": " .. impl:: implement main function\n    :id: REQ_002\n    :links: IMPL_001, IMPL_002\n\n    This is content for the main function implementation.\n ",
+    "need": {
+      "type": "impl",
+      "title": "implement main function",
+      "content": "This is content for the main function implementation.",
+      "id": "REQ_002",
+      "links": [
+        "IMPL_001",
+        " IMPL_002"
+      ]
+    },
+    "type": "rst"
+  }
+]

tests/conftest.py

@@ -99,9 +99,9 @@ def serialize(self, data, **_kwargs):
 
 @pytest.fixture
 def snapshot_marks(snapshot):
-    """Snapshot fixture for reqif.
+    """Snapshot fixture for markers.
 
-    Sanitize the reqif, to make the snapshots reproducible.
+    Sanitize the markers, to make the snapshots reproducible.
     """
     return snapshot.with_defaults(extension_class=AnchorsSnapshotExtension)
 

tests/fixture_files/analyse_rst.yml

@@ -67,3 +67,46 @@ link_options_rst_marker:
     int main() {
       return 0;
     }
+
+link_options_rst_marker:
+  dummy_1.c: |
+    /*
+     * @rst
+     * .. impl:: implement main function
+     *    :id: REQ_001
+     *    :links: IMPL_001, IMPL_002
+     *
+     *    This is content for the main function implementation.
+     * @endrst
+    */
+    int main() {
+      return 0;
+    }
+
+warning_invalid_type:
+  dummy_1.c: |
+    /*
+     * @rst
+     * .. imp@:: implement main function
+     *    :id: REQ_001
+     *    :links: IMPL_001, IMPL_002
+     *
+     *    This is content for the main function implementation.
+     * @endrst
+    */
+    int main() {
+      return 0;
+    }
+    /*
+     * @rst
+     * .. impl:: implement main function
+     *    :id: REQ_002
+     *    :links: IMPL_001, IMPL_002
+     *
+     *    This is content for the main function implementation.
+     * @endrst
+    */
+    int func1() {
+      return 0;
+    }
+  warnings_cnt: 1

tests/test_analyse.py

@@ -161,14 +161,25 @@ def test_analyse_rst(
     src_analyse.dump_marked_content(tmp_path)
     dumped_content = tmp_path / "marked_content.json"
 
-    # assert src_analyse.rst_warnings
     assert dumped_content.exists()
 
     with dumped_content.open("r") as f:
         marked_content = json.load(f)
     # normalize filepath
-    for obj in marked_content:
-        obj["filepath"] = (
-            Path(obj["filepath"]).relative_to(src_analyse_config.src_dir)
-        ).as_posix()
+    normalize_file_path(marked_content, src_analyse_config.src_dir)
     assert marked_content == snapshot_marks
+
+    if "warnings_cnt" in content:
+        assert len(src_analyse.rst_warnings) == content["warnings_cnt"]
+        src_analyse.dump_warnings(tmp_path)
+        dumped_warnings = tmp_path / "analyse_warnings.json"
+        assert dumped_warnings.exists()
+
+
+def normalize_file_path(analysed_content: list[dict[str, Any]], src_dir: Path) -> None:
+    """Normalize the file paths in the analysed content to be relative to src_dir.
+
+    It is for the test results to be consistent across different environments.
+    """
+    for obj in analysed_content:
+        obj["filepath"] = (Path(obj["filepath"]).relative_to(src_dir)).as_posix()