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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 1.0.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>
@@ -21,6 +21,9 @@ Requires-Dist: tree-sitter-cpp>=0.23.4
 Requires-Dist: giturlparse>=0.12.0
 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.0.0 → sphinx_codelinks-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "1.0.0"
+version = "1.2.0"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [
@@ -27,13 +27,45 @@ dependencies = [
   # Compiling issue on manylinux aarch64 image, so install from git instead of Pypi
   # https://github.com/tree-sitter/py-tree-sitter/issues/386#issuecomment-3101430799
   "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.0.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,
@@ -322,7 +329,7 @@ class SourceAnalyse:
             if not filepath:
                 continue
             tagged_scope: TreeSitterNode | None = utils.find_associated_scope(
-                src_comment.node
+                src_comment.node, self.analyse_config.comment_type
             )
             if self.analyse_config.get_need_id_refs:
                 anchors = self.extract_anchors(

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

@@ -2,12 +2,7 @@ from dataclasses import dataclass
 from enum import Enum
 import logging
 
-from sphinx_codelinks.config import (
-    ESCAPE,
-    SUPPORTED_COMMENT_TYPES,
-    UNIX_NEWLINE,
-    OneLineCommentStyle,
-)
+from sphinx_codelinks.config import ESCAPE, UNIX_NEWLINE, OneLineCommentStyle
 
 # initialize logger
 logger = logging.getLogger(__name__)
@@ -36,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:
@@ -58,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()
@@ -204,15 +200,3 @@ def is_newline_in_field(field: str) -> bool:
     Check if the field contains a new line character.
     """
     return UNIX_NEWLINE in field
-
-
-def get_file_types(comment_type: str) -> list[str] | None:
-    """
-    Get the list of file types to be discovered.
-    """
-    file_types = (
-        list(SUPPORTED_COMMENT_TYPES)
-        if comment_type in SUPPORTED_COMMENT_TYPES
-        else None
-    )
-    return file_types

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

@@ -12,6 +12,25 @@ from tree_sitter import Node as TreeSitterNode
 from sphinx_codelinks.config import UNIX_NEWLINE, CommentCategory
 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
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.INFO)
@@ -35,6 +54,12 @@ PYTHON_QUERY = """
                 (class_definition (block (expression_statement (string)) @comment))
             """
 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:
@@ -52,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
@@ -63,6 +89,21 @@ def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
 
         parsed_language = Language(tree_sitter_python.language())
         query = Query(parsed_language, PYTHON_QUERY)
+    elif comment_type == CommentType.cs:
+        import tree_sitter_c_sharp  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_c_sharp.language())
+        query = Query(parsed_language, C_SHARP_QUERY)
+    elif comment_type == CommentType.yaml:
+        import tree_sitter_yaml  # noqa: PLC0415
+
+        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)
@@ -78,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:
@@ -90,39 +132,133 @@ def extract_comments(
     return captures.get("comment")
 
 
-def find_enclosing_scope(node: TreeSitterNode) -> TreeSitterNode | None:
+def find_enclosing_scope(
+    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
+) -> TreeSitterNode | None:
     """Find the enclosing scope of a comment."""
+    scope_types = SCOPE_NODE_TYPES.get(comment_type, SCOPE_NODE_TYPES[CommentType.cpp])
     current: TreeSitterNode = node
     while current:
-        if current.type in {"function_definition", "class_definition"}:
+        if current.type in scope_types:
             return current
         current: TreeSitterNode | None = current.parent  # type: ignore[no-redef]  # required for node traversal
     return None
 
 
-def find_next_scope(node: TreeSitterNode) -> TreeSitterNode | None:
+def find_next_scope(
+    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
+) -> TreeSitterNode | None:
     """Find the next scope of a comment."""
+    scope_types = SCOPE_NODE_TYPES.get(comment_type, SCOPE_NODE_TYPES[CommentType.cpp])
     current: TreeSitterNode = node
     while current:
-        if current.type in {"function_definition", "class_definition"}:
+        if current.type in scope_types:
             return current
         current: TreeSitterNode | None = current.next_named_sibling  # type: ignore[no-redef]  # required for node traversal
         if current and current.type == "block":
             for child in current.named_children:
-                if child.type in {"function_definition", "class_definition"}:
+                if child.type in scope_types:
                     return child
     return None
 
 
-def find_associated_scope(node: TreeSitterNode) -> TreeSitterNode | None:
+def _find_yaml_structure_in_block_node(
+    block_node: TreeSitterNode,
+) -> TreeSitterNode | None:
+    """Find YAML structure elements within a block_node."""
+    for grandchild in block_node.named_children:
+        if grandchild.type == "block_mapping":
+            for ggchild in grandchild.named_children:
+                if ggchild.type == "block_mapping_pair":
+                    return ggchild
+        elif grandchild.type == "block_sequence":
+            for ggchild in grandchild.named_children:
+                if ggchild.type == "block_sequence_item":
+                    return ggchild
+    return None
+
+
+def find_yaml_next_structure(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find the next YAML structure element after the comment node."""
+    current = node.next_named_sibling
+    while current:
+        if current.type in {
+            "block_mapping_pair",
+            "block_sequence_item",
+            "flow_mapping",
+            "flow_sequence",
+        }:
+            return current
+        if current.type == "document":
+            for child in current.named_children:
+                if child.type == "block_node":
+                    result = _find_yaml_structure_in_block_node(child)
+                    if result:
+                        return result
+        if current.type == "block_node":
+            result = _find_yaml_structure_in_block_node(current)
+            if result:
+                return result
+        current = current.next_named_sibling
+    return None
+
+
+def find_yaml_prev_sibling_on_same_row(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find a previous named sibling that is on the same row as the comment."""
+    comment_row = node.start_point.row
+    current = node.prev_named_sibling
+
+    while current:
+        # Check if this sibling ends on the same row as the comment starts
+        # This indicates it's an inline comment
+        if current.end_point.row == comment_row:
+            return current
+        # If we find a sibling that ends before the comment row, we can stop
+        # as we won't find any siblings on the same row going backwards
+        if current.end_point.row < comment_row:
+            break
+        current = current.prev_named_sibling
+
+    return None
+
+
+def find_yaml_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find the YAML structure (key-value pair, list item, etc.) associated with a comment."""
+    # First, check if this is an inline comment by looking for a previous sibling on the same row
+    prev_sibling_same_row = find_yaml_prev_sibling_on_same_row(node)
+    if prev_sibling_same_row:
+        return prev_sibling_same_row
+
+    # If no previous sibling on same row, try to find the next named sibling (structure after the comment)
+    structure = find_yaml_next_structure(node)
+    if structure:
+        return structure
+
+    # If no next sibling found, traverse up to find parent structure
+    parent = node.parent
+    while parent:
+        if parent.type in {"block_mapping_pair", "block_sequence_item"}:
+            return parent
+        parent = parent.parent
+
+    return None
+
+
+def find_associated_scope(
+    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
+) -> TreeSitterNode | None:
     """Find the associated scope of a comment."""
+    if comment_type == CommentType.yaml:
+        # YAML uses different structure association logic
+        return find_yaml_associated_structure(node)
+
     if node.type == CommentCategory.docstring:
         # Only for python's docstring
-        return find_enclosing_scope(node)
+        return find_enclosing_scope(node, comment_type)
     # General comments regardless of comment types
-    associated_scope = find_next_scope(node)
+    associated_scope = find_next_scope(node, comment_type)
     if not associated_scope:
-        associated_scope = find_enclosing_scope(node)
+        associated_scope = find_enclosing_scope(node, comment_type)
     return associated_scope
 
 
@@ -219,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.0.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.0.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/config.py

@@ -18,9 +18,14 @@ from sphinx_codelinks.source_discover.source_discover import SourceDiscover
 UNIX_NEWLINE = "\n"
 
 
-COMMENT_MARKERS = {CommentType.cpp: ["//", "/*"], CommentType.python: ["#"]}
+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: ["//", "/*", "///"],
+}
 ESCAPE = "\\"
-SUPPORTED_COMMENT_TYPES = {"c", "h", "cpp", "hpp", "py"}
 
 
 class CommentCategory(str, Enum):
@@ -47,7 +52,7 @@ class NeedIdRefsConfig:
     @classmethod
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return cast(dict[str, Any], _field.metadata["schema"])  # type: ignore[explicit-any]
         return None
 
@@ -86,7 +91,7 @@ class MarkedRstConfig:
     @classmethod
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return cast(dict[str, Any], _field.metadata["schema"])  # type: ignore[explicit-any]
         return None
 
@@ -219,14 +224,14 @@ class OneLineCommentStyle:
     @classmethod
     def get_required_fields(cls, name: str) -> list[str] | None:
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING:
+        if _field.metadata:
             return cast(list[str], _field.metadata["required_fields"])
         return None
 
     @classmethod
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return cast(dict[str, Any], _field.metadata["schema"])  # type: ignore[explicit-any]
         return None
 
@@ -300,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
@@ -314,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
@@ -356,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."""
 
@@ -370,7 +383,7 @@ class SourceAnalyseConfig:
     @classmethod
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return cast(dict[str, Any], _field.metadata["schema"])  # type: ignore[explicit-any]
         return None
 
@@ -566,7 +579,7 @@ class CodeLinksConfig:
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         """Get the schema for a config item."""
         _field = next(field for field in fields(cls) if field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return _field.metadata["schema"]  # type: ignore[no-any-return]
         return None
 
@@ -760,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(
@@ -791,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)
 
@@ -853,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.0.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/needextend_write.py

@@ -1,7 +1,7 @@
-"""Covert the generated JSON file created by CodeLinks anaylse to need-extend in RST."""
+"""Convert the generated JSON file created by CodeLinks analyse to need-extend in RST."""
 
 from collections import deque
-from dataclasses import MISSING, dataclass, field, fields
+from dataclasses import dataclass, field, fields
 from os import linesep
 from string import Template
 from typing import Any, TypedDict, cast
@@ -105,7 +105,7 @@ class MarkedContentSchema:
     @classmethod
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return cast(dict[str, Any], _field.metadata["schema"])  # type: ignore[explicit-any]
         return None
 
@@ -165,7 +165,7 @@ def convert_marked_content(
     remote_url_field: str = "remote-url",
     title: str | None = None,
 ) -> tuple[list[str], list[str]]:
-    """Convert marked objects extracted by anaylse CLI to needextend in RST"""
+    """Convert marked objects extracted by analyse CLI to needextend in RST"""
     errors = []
     needextend_texts: list[str] = []
     intersted_objs = [

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

@@ -1,16 +1,26 @@
-from dataclasses import MISSING, dataclass, field, fields
+from dataclasses import dataclass, field, fields
 from enum import Enum
 from pathlib import Path
 from typing import Any, Required, TypedDict, cast
 
 from jsonschema import ValidationError, validate
 
-COMMENT_FILETYPE = {"cpp": ["c", "cpp", "h", "hpp"], "python": ["py"]}
+COMMENT_FILETYPE = {
+    "cpp": ["c", "ci", "cpp", "cc", "cxx", "h", "hpp", "hxx", "hh", "ihl"],
+    "python": ["py"],
+    "cs": ["cs"],
+    "yaml": ["yml", "yaml"],
+    "rust": ["rs"],
+}
 
 
 class CommentType(str, Enum):
     python = "python"
     cpp = "cpp"
+    cs = "cs"
+    yaml = "yaml"
+    # @Support Rust style comments, IMPL_RUST_1, impl, [FE_RUST];
+    rust = "rust"
 
 
 class SourceDiscoverSectionConfigType(TypedDict, total=False):
@@ -73,7 +83,7 @@ class SourceDiscoverConfig:
     @classmethod
     def get_schema(cls, name: str) -> dict[str, Any] | None:  # type: ignore[explicit-any]
         _field = next(_field for _field in fields(cls) if _field.name is name)
-        if _field.metadata is not MISSING and "schema" in _field.metadata:
+        if _field.metadata and "schema" in _field.metadata:
             return cast(dict[str, Any], _field.metadata["schema"])  # type: ignore[explicit-any]
         return None
 

{sphinx_codelinks-1.0.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.0.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -33,6 +33,15 @@ else:
 logger = logging.getLogger(__name__)
 
 
+def get_rel_path(doc_path: Path, code_path: Path, base_dir: Path) -> tuple[Path, Path]:
+    """Get the relative path from the document to the source code file and vice versa."""
+    doc_depth = len(doc_path.parents) - 1
+    src_rel_path = Path(*[".."] * doc_depth) / code_path.relative_to(base_dir)
+    code_depth = len(code_path.relative_to(base_dir).parents) - 1
+    doc_rel_path = Path(*[".."] * code_depth) / doc_path
+    return src_rel_path, doc_rel_path.with_suffix(".html")
+
+
 def generate_str_link_name(
     oneline_need: OneLineNeed,
     target_filepath: Path,
@@ -67,13 +76,12 @@ class SourceTracing(nodes.General, nodes.Element):
 
 
 class SourceTracingDirective(SphinxDirective):
-    required_arguments = 1
+    required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = True
     # this enables content in the directive
-    has_content = True
+    has_content = False
     option_spec: ClassVar[dict[str, Callable[[str], str]] | None] = {
-        "id": directives.unchanged_required,
         "project": directives.unchanged_required,
         "file": directives.unchanged_required,
         "directory": directives.unchanged_required,
@@ -84,7 +92,6 @@ class SourceTracingDirective(SphinxDirective):
         validate_option(self.options)
 
         project = self.options["project"]
-        title = self.arguments[0]
         # get source tracing config
         src_trace_sphinx_config = CodeLinksConfig.from_sphinx(self.env.config)
 
@@ -99,7 +106,6 @@ class SourceTracingDirective(SphinxDirective):
         # the directory where the source files are copied to
         target_dir = out_dir / src_dir.name
 
-        extra_options = {"project": project}
         source_files = self.get_src_files(self.options, src_dir, src_discover_config)
 
         # add source files into the dependency
@@ -110,23 +116,16 @@ 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()
 
-        needs = []
-
-        # create the need for src-trace directive
-        src_trace_need = add_need(
-            app=self.env.app,  # The Sphinx application object
-            state=self.state,  # The docutils state object
-            docname=self.env.docname,  # The current document name
-            lineno=self.lineno,  # The line number where the directive is used
-            need_type="srctrace",  # The type of the need
-            title=title,  # The title of the need
-            **extra_options,
-        )
-        needs.extend(src_trace_need)
-
         dirs = {
             "src_dir": src_dir,
             "out_dir": out_dir,
@@ -145,7 +144,7 @@ class SourceTracingDirective(SphinxDirective):
                 to_remove_str = to_remove_str.replace("\\", "\\\\")
             self.env.config.needs_string_links[local_url_field] = {
                 "regex": r"^(?P<value>.+?)\.[^\.]+#L(?P<lineno>\d+)",
-                "link_url": ("file://{{value}}.html#L-{{lineno}}"),
+                "link_url": ("{{value}}.html#L-{{lineno}}"),
                 "link_name": f"{{{{value | replace('{to_remove_str}', '')}}}}#L{{{{lineno}}}}",
                 "options": [local_url_field],
             }
@@ -180,18 +179,16 @@ class SourceTracingDirective(SphinxDirective):
             remote_url_field,
             dirs,
         )
-        if rendered_needs:
-            needs.extend(rendered_needs)
 
         # for post-processing of need links
         # https://github.com/useblocks/sphinx-needs/issues/1210
         add_doc(self.env, self.env.docname)
 
-        return needs
+        return rendered_needs
 
     def get_src_files(
         self,
-        extra_options: dict[str, str],
+        additional_options: dict[str, str],
         src_dir: Path,
         src_discover_config: SourceDiscoverConfig,
     ) -> list[Path]:
@@ -201,14 +198,14 @@ class SourceTracingDirective(SphinxDirective):
             file: str = self.options["file"]
             filepath = src_dir / file
             source_files.append(filepath.resolve())
-            extra_options["file"] = file
+            additional_options["file"] = file
         else:
             directory = self.options.get("directory")
             if directory is None:
                 # when neither "file" and "directory" are given, the project root dir is by default
                 directory = "./"
             else:
-                extra_options["directory"] = directory
+                additional_options["directory"] = directory
             dir_path = src_dir / directory
             # create a new config for the specified directory
             src_discover = SourceDiscoverConfig(
@@ -259,7 +256,7 @@ class SourceTracingDirective(SphinxDirective):
             # mapping between lineno and need link in docs for local url
 
             # The link to the documentation page for the source file
-            docs_href = f"{dirs['out_dir'] / self.env.docname}.html"
+
             if local_url_field:
                 # copy files to _build/html
                 target_filepath.parent.mkdir(parents=True, exist_ok=True)
@@ -268,8 +265,15 @@ class SourceTracingDirective(SphinxDirective):
             remote_link_name = None
             if local_url_field:
                 # generate link name
+                # calculate the relative path from the current doc to the target file
+                local_rel_path, docs_href = get_rel_path(
+                    Path(self.env.docname), target_filepath, dirs["out_dir"]
+                )
                 local_link_name = generate_str_link_name(
-                    oneline_need, target_filepath, dirs, local=True
+                    oneline_need,
+                    local_rel_path,
+                    dirs,
+                    local=True,
                 )
             if remote_url_field:
                 remote_link_name = generate_str_link_name(

{sphinx_codelinks-1.0.0 → sphinx_codelinks-1.2.0}/src/sphinx_codelinks/sphinx_extension/source_tracing.py

@@ -35,7 +35,34 @@ from sphinx_codelinks.sphinx_extension.html_wrapper import html_wrapper
 logger = logging.getLogger(__name__)
 
 
+def _check_sphinx_needs_dependency(app: Sphinx) -> bool:
+    """Check if sphinx-needs is actually loaded as an extension."""
+    # Check if sphinx-needs is in the loaded extensions
+    if "sphinx_needs" not in app.extensions:
+        error_msg = (
+            "sphinx-codelinks requires sphinx-needs to be loaded as an extension.\n"
+            "Please ensure 'sphinx_needs' is properly installed and added to your extensions list in conf.py:\n"
+            "   extensions = ['sphinx_needs', 'sphinx_codelinks', ...]\n"
+            f"Currently loaded extensions: {list(app.extensions.keys())}\n"
+            f"Configured extensions: {app.config.extensions}"
+        )
+        logger.error(error_msg)
+        return False
+    return True
+
+
 def setup(app: Sphinx) -> dict[str, Any]:  # type: ignore[explicit-any]
+    # Check if sphinx-needs is available and properly configured
+    if not _check_sphinx_needs_dependency(app):
+        logger.error(
+            "Failed to initialize sphinx-codelinks due to missing sphinx-needs dependency"
+        )
+        return {
+            "version": "builtin",
+            "parallel_read_safe": True,
+            "parallel_write_safe": True,
+        }
+
     app.add_node(SourceTracing)
     app.add_directive("src-trace", SourceTracingDirective)
     CodeLinksConfig.add_config_values(app)
@@ -69,7 +96,7 @@ def add_custom_css(  # type: ignore[explicit-any]
     app: Sphinx,
     pagename: str,
     templatename: str,
-    context: dict[str, Any],
+    _context: dict[str, Any],
     _doctree: Any,
 ) -> None:
     target_htmls = {
@@ -78,11 +105,7 @@ def add_custom_css(  # type: ignore[explicit-any]
     }
 
     if pagename in target_htmls and templatename == "page.html":
-        if "css_files" not in context:
-            context["css_files"] = []
-        context["css_files"].append(
-            "_static/source_tracing/ub_sct.css"
-        )  # Add the custom CSS file to the context
+        app.add_css_file("_static/source_tracing/ub_sct.css")
 
 
 def generate_code_page(