sphinx-codelinks 1.1.0__tar.gz → 1.2.0__tar.gz

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 1.1.0
+Version: 1.2.0
 Summary: Fast Source Code Traceability for Sphinx-Needs
 Author-email: team useblocks <info@useblocks.com>
 Maintainer-email: Marco Heinemann <marco.heinemann@useblocks.com>, Jui-Wen Chen <jui-wen.chen@useblocks.com>
@@ -23,6 +23,7 @@ Requires-Dist: tree-sitter-python>=0.23.6
 Requires-Dist: tree-sitter~=0.25.1
 Requires-Dist: tree-sitter-c-sharp>=0.23.1
 Requires-Dist: tree-sitter-yaml>=0.7.1
+Requires-Dist: tree-sitter-rust>=0.23.0
 
 # Sphinx CodeLinks
 

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "1.1.0"
+version = "1.2.0"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [
@@ -29,12 +29,43 @@ dependencies = [
   "tree-sitter~=0.25.1",
   "tree-sitter-c-sharp>=0.23.1",
   "tree-sitter-yaml>=0.7.1",
+  "tree-sitter-rust>=0.23.0",
 ]
 
 [build-system]
 requires = ["flit_core >=3.4,<4"]
 build-backend = "flit_core.buildapi"
 
+[dependency-groups]
+testing = [
+  "pytest>=8.2.2",
+  "pytest-cov>=5.0.0",
+  "pytest-docker>=3.1.2",
+  "syrupy>=4.9.1",
+  "psutil>=7.0.0",
+  "moto ~= 5.0",
+  "toml>=0.10.2",
+  "furo>=2024.5.6",
+]
+docs = [
+  "furo>=2024.5.6",
+  "myst-parser>=4.0.0",
+  "sphinx-design>=0.6.1",
+  "sphinx-code-tabs>=0.5.5",
+  "sphinxcontrib-typer>=0.5.1",
+  "sphinxcontrib-video>=0.4.1",
+]
+mypy = [
+  "mypy>=1.12.1",
+  "pydantic ~= 2.9",
+  "types-docutils",
+  "types-Pygments",
+  "types-psutil>=7.0.0.20250218",
+  "types-jsonschema>=4.23.0.20241208",
+]
+ruff = ["ruff>=0.8.0"]
+build = ["simple-build>=0.0.2", "shiv>=1.0.8"]
+
 [tool.rye]
 managed = true
 dev-dependencies = [

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/analyse/analyse.py

@@ -65,7 +65,11 @@ class SourceAnalyse:
         self.oneline_needs: list[OneLineNeed] = []
         self.marked_rst: list[MarkedRst] = []
         self.all_marked_content: list[NeedIdRefs | OneLineNeed | MarkedRst] = []
-        self.git_root: Path | None = utils.locate_git_root(self.analyse_config.src_dir)
+        # Use explicitly configured git_root if provided, otherwise auto-detect
+        if self.analyse_config.git_root is not None:
+            self.git_root: Path | None = self.analyse_config.git_root.resolve()
+        else:
+            self.git_root = utils.locate_git_root(self.analyse_config.src_dir)
         self.git_remote_url: str | None = (
             utils.get_remote_url(self.git_root) if self.git_root else None
         )
@@ -127,6 +131,7 @@ class SourceAnalyse:
                 yield marker, need_ids, row_offset, start_column, end_column
             row_offset += 1
 
+    # @Extract need ID references from code comments, IMPL_LNK_1, impl, [FE_LNK]
     def extract_anchors(
         self,
         text: str,
@@ -197,20 +202,21 @@ class SourceAnalyse:
                 if not src_comment.source_file:
                     row_offset += 1
                     continue
-                self.oneline_warnings.append(
-                    AnalyseWarning(
-                        str(src_comment.source_file.filepath),
-                        src_comment.node.start_point.row + row_offset + 1,
-                        resolved.msg,
-                        MarkedContentType.need,
-                        resolved.sub_type.value,
-                    )
+                lineno = src_comment.node.start_point.row + row_offset + 1
+                warning = AnalyseWarning(
+                    str(src_comment.source_file.filepath),
+                    lineno,
+                    resolved.msg,
+                    MarkedContentType.need,
+                    resolved.sub_type.value,
                 )
+                self.oneline_warnings.append(warning)
                 row_offset += 1
                 continue
             yield resolved, row_offset
             row_offset += 1
 
+    # @Extract one-line traceability needs from comments, IMPL_ONE_1, impl, [FE_DEF, FE_CMT]
     def extract_oneline_needs(
         self,
         text: str,
@@ -258,6 +264,7 @@ class SourceAnalyse:
             )
         return oneline_needs
 
+    # @Extract marked reStructuredText blocks from comments, IMPL_MRST_1, impl, [FE_RST_EXTRACTION]
     def extract_marked_rst(
         self,
         text: str,

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/analyse/oneline_parser.py

@@ -31,6 +31,7 @@ class OnelineParserInvalidWarning:
     msg: str
 
 
+# @One-line comment parser for traceability markers, IMPL_OLP_1, impl, [FE_DEF, FE_CMT]
 def oneline_parser(  # noqa: PLR0912, PLR0911 # handel warnings
     oneline: str, oneline_config: OneLineCommentStyle
 ) -> dict[str, str | list[str] | int] | OnelineParserInvalidWarning | None:
@@ -53,7 +54,7 @@ def oneline_parser(  # noqa: PLR0912, PLR0911 # handel warnings
 
     # extract the string wrapped by start and end
     start_idx = start_idx + len(oneline_config.start_sequence)
-    string = oneline[start_idx:end_idx]
+    string = oneline[start_idx:end_idx].strip()
 
     # numbers of needs_fields which are required
     cnt_required_fields = oneline_config.get_cnt_required_fields()

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/analyse/utils.py

@@ -14,10 +14,21 @@ from sphinx_codelinks.source_discover.config import CommentType
 
 # Language-specific node types for scope detection
 SCOPE_NODE_TYPES = {
+    # @Python Scope Node Types, IMPL_PY_2, impl, [FE_PY]
     CommentType.python: {"function_definition", "class_definition"},
+    # @C and C++ Scope Node Types, IMPL_C_2, impl, [FE_C_SUPPORT, FE_CPP]
     CommentType.cpp: {"function_definition", "class_definition"},
     CommentType.cs: {"method_declaration", "class_declaration", "property_declaration"},
     CommentType.yaml: {"block_mapping_pair", "block_sequence_item", "document"},
+    # @Rust Scope Node Types, IMPL_RUST_2, impl, [FE_RUST];
+    CommentType.rust: {
+        "function_item",
+        "struct_item",
+        "enum_item",
+        "impl_item",
+        "trait_item",
+        "mod_item",
+    },
 }
 
 # initialize logger
@@ -45,6 +56,10 @@ PYTHON_QUERY = """
 CPP_QUERY = """(comment) @comment"""
 C_SHARP_QUERY = """(comment) @comment"""
 YAML_QUERY = """(comment) @comment"""
+RUST_QUERY = """
+    (line_comment) @comment
+    (block_comment) @comment
+"""
 
 
 def is_text_file(filepath: Path, sample_size: int = 2048) -> bool:
@@ -62,6 +77,7 @@ def is_text_file(filepath: Path, sample_size: int = 2048) -> bool:
         return False
 
 
+# @Tree-sitter parser initialization for multiple languages, IMPL_LANG_1, impl, [FE_C_SUPPORT, FE_CPP, FE_PY, FE_YAML, FE_RUST]
 def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
     if comment_type == CommentType.cpp:
         import tree_sitter_cpp  # noqa: PLC0415
@@ -83,6 +99,11 @@ def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
 
         parsed_language = Language(tree_sitter_yaml.language())
         query = Query(parsed_language, YAML_QUERY)
+    elif comment_type == CommentType.rust:
+        import tree_sitter_rust  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_rust.language())
+        query = Query(parsed_language, RUST_QUERY)
     else:
         raise ValueError(f"Unsupported comment style: {comment_type}")
     parser = Parser(parsed_language)
@@ -98,6 +119,7 @@ def wrap_read_callable_point(
     return read_callable_byte_offset
 
 
+# @Comment extraction from source code using tree-sitter, IMPL_EXTR_1, impl, [FE_DEF]
 def extract_comments(
     src_string: ByteString, parser: Parser, query: Query
 ) -> list[TreeSitterNode] | None:
@@ -333,6 +355,7 @@ class ExtractedRstType(TypedDict):
     end_idx: int
 
 
+# @Extract reStructuredText blocks embedded in comments, IMPL_RST_1, impl, [FE_RST_EXTRACTION]
 def extract_rst(
     text: str, start_marker: str, end_marker: str
 ) -> ExtractedRstType | None:

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/cmd.py

@@ -56,7 +56,7 @@ OptQuiet: TypeAlias = Annotated[  # noqa: UP040 # has to be TypeAlias
 
 
 @app.command(no_args_is_help=True)
-def analyse(
+def analyse(  # noqa: PLR0912   # for CLI, so it needs the branches
     config: Annotated[
         Path,
         typer.Argument(
@@ -90,6 +90,7 @@ def analyse(
     ] = None,
 ) -> None:
     """Analyse marked content in source code."""
+    # @CLI command to analyse source code and extract traceability markers, IMPL_CLI_ANALYZE, impl, [FE_CLI_ANALYZE]
 
     data: CodeLinksConfigType = load_config_from_toml(config)
 
@@ -140,6 +141,12 @@ def analyse(
         analyse_config.src_files = src_discover.source_paths
         analyse_config.src_dir = Path(src_discover.src_discover_config.src_dir)
 
+        # git_root shall be relative to the config file's location (like src_dir)
+        if analyse_config.git_root is not None:
+            analyse_config.git_root = (
+                config.parent / analyse_config.git_root
+            ).resolve()
+
         analyse_errors = analyse_config.check_fields_configuration()
         errors.extend(analyse_errors)
         if errors:
@@ -150,6 +157,15 @@ def analyse(
     codelinks_config.projects = specifed_project_configs
     analyse_projects = AnalyseProjects(codelinks_config)
     analyse_projects.run()
+
+    # Output warnings to console for CLI users
+    for src_analyse in analyse_projects.projects_analyse.values():
+        for warning in src_analyse.oneline_warnings:
+            logger.warning(
+                f"Oneline parser warning in {warning.file_path}:{warning.lineno} "
+                f"- {warning.sub_type}: {warning.msg}",
+            )
+
     analyse_projects.dump_markers()
 
 
@@ -183,6 +199,7 @@ def discover(
             help="Glob patterns to be included.",
         ),
     ] = [],  # noqa: B006   # to show the default value on CLI
+    # @CLI command to discover source files recursively with gitignore support, IMPL_CLI_DISCOVER, impl, [FE_CLI_DISCOVER]
     gitignore: Annotated[
         bool,
         typer.Option(
@@ -234,6 +251,7 @@ def write_rst(  # noqa: PLR0913  # for CLI, so it takes as many as it requires
             resolve_path=True,
         ),
     ],
+    # @CLI command to generate needextend RST file from extracted markers, IMPL_CLI_WRITE, impl, [FE_CLI_WRITE]
     outpath: Annotated[
         Path,
         typer.Option(

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/config.py

@@ -19,7 +19,9 @@ UNIX_NEWLINE = "\n"
 
 
 COMMENT_MARKERS = {
+    # @Support C and C++ style comments, IMPL_C_1, impl, [FE_C_SUPPORT, FE_CPP]
     CommentType.cpp: ["//", "/*"],
+    # @Support Python style comments, IMPL_PY_1, impl, [FE_PY]
     CommentType.python: ["#"],
     CommentType.cs: ["//", "/*", "///"],
 }
@@ -303,6 +305,7 @@ class AnalyseSectionConfigType(TypedDict, total=False):
     get_oneline_needs: bool
     get_rst: bool
     outdir: str
+    git_root: str
     need_id_refs: NeedIdRefsConfigType
     marked_rst: MarkedRstConfigType
     oneline_comment_style: OneLineCommentStyleType
@@ -317,6 +320,7 @@ class SourceAnalyseConfigType(TypedDict, total=False):
     get_need_id_refs: bool
     get_oneline_needs: bool
     get_rst: bool
+    git_root: Path | None
     need_id_refs_config: NeedIdRefsConfig
     marked_rst_config: MarkedRstConfig
     oneline_comment_style: OneLineCommentStyle
@@ -359,6 +363,12 @@ class SourceAnalyseConfig:
     get_rst: bool = field(default=False, metadata={"schema": {"type": "boolean"}})
     """Whether to extract rst texts from comments"""
 
+    git_root: Path | None = field(
+        default=None, metadata={"schema": {"type": ["string", "null"]}}
+    )
+    """Explicit path to the Git repository root. If not set, it will be auto-detected
+    by traversing parent directories. Useful for Bazel builds or deeply nested configs."""
+
     need_id_refs_config: NeedIdRefsConfig = field(default_factory=NeedIdRefsConfig)
     """Configuration for extracting need id references from comments."""
 
@@ -763,9 +773,11 @@ def convert_analyse_config(
     if config_dict:
         for k, v in config_dict.items():
             if k not in {"online_comment_style", "need_id_refs", "marked_rst"}:
-                analyse_config_dict[k] = (  # type: ignore[literal-required]  # dynamical assignment
-                    Path(v) if k == "src_dic" and isinstance(v, str) else v
-                )
+                # Convert string paths to Path objects
+                if k in {"src_dir", "git_root"} and isinstance(v, str):
+                    analyse_config_dict[k] = Path(v)  # type: ignore[literal-required]
+                else:
+                    analyse_config_dict[k] = v  # type: ignore[literal-required]  # dynamical assignment
 
         # Get oneline_comment_style configuration
         oneline_comment_style_dict: OneLineCommentStyleType | None = config_dict.get(
@@ -794,6 +806,15 @@ def convert_analyse_config(
     if src_discover:
         analyse_config_dict["src_files"] = src_discover.source_paths
         analyse_config_dict["src_dir"] = src_discover.src_discover_config.src_dir
+        try:
+            analyse_config_dict["comment_type"] = CommentType(
+                src_discover.src_discover_config.comment_type
+            )
+        except ValueError:
+            # If invalid comment_type, keep the string value
+            # Validation will catch this error later
+            comment_type_str: str = src_discover.src_discover_config.comment_type
+            analyse_config_dict["comment_type"] = comment_type_str  # type: ignore[typeddict-item]
 
     return SourceAnalyseConfig(**analyse_config_dict)
 
@@ -856,4 +877,13 @@ def generate_project_configs(
         )
         analyse_config = convert_analyse_config(analyse_section_config)
         analyse_config.get_oneline_needs = True  # force to get oneline_need
+        # Copy comment_type from source_discover_config to analyse_config
+        try:
+            analyse_config.comment_type = CommentType(
+                source_discover_config.comment_type
+            )
+        except ValueError:
+            # If invalid comment_type, keep the string value
+            # Validation will catch this error later
+            analyse_config.comment_type = source_discover_config.comment_type  # type: ignore[assignment]
         project_config["analyse_config"] = analyse_config

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/source_discover/config.py

@@ -10,6 +10,7 @@ COMMENT_FILETYPE = {
     "python": ["py"],
     "cs": ["cs"],
     "yaml": ["yml", "yaml"],
+    "rust": ["rs"],
 }
 
 
@@ -18,6 +19,8 @@ class CommentType(str, Enum):
     cpp = "cpp"
     cs = "cs"
     yaml = "yaml"
+    # @Support Rust style comments, IMPL_RUST_1, impl, [FE_RUST];
+    rust = "rust"
 
 
 class SourceDiscoverSectionConfigType(TypedDict, total=False):

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/source_discover/source_discover.py

@@ -13,6 +13,7 @@ from sphinx_codelinks.source_discover.config import (
 )
 
 
+# @Source code file discovery with gitignore support, IMPL_DISC_1, impl, [FE_DISCOVERY, FE_CLI_DISCOVER]
 class SourceDiscover:
     def __init__(self, src_discover_config: SourceDiscoverConfig):
         self.src_discover_config = src_discover_config

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -116,6 +116,13 @@ class SourceTracingDirective(SphinxDirective):
         analyse_config = src_trace_conf["analyse_config"]
         analyse_config.src_dir = src_dir
         analyse_config.src_files = source_files
+        # git_root shall be relative to the config file's location (if provided)
+        if analyse_config.git_root:
+            conf_dir = Path(self.env.app.confdir)
+            if src_trace_sphinx_config.config_from_toml:
+                src_trace_toml_path = Path(src_trace_sphinx_config.config_from_toml)
+                conf_dir = conf_dir / src_trace_toml_path.parent
+            analyse_config.git_root = (conf_dir / analyse_config.git_root).resolve()
         src_analyse = SourceAnalyse(analyse_config)
         src_analyse.run()