link impl and test suits/files

Author: patdhlk

docs/source/components/features.rst

@@ -30,7 +30,8 @@ Features
 .. feature:: Discover Source Code Files
    :id: FE_DISCOVERY
 
-   Discover source code files in a specified root directory. The root directory shall be configurable.
+   Discover source code files in a specified root directory.
+   The root directory shall be configurable.
 
 .. feature:: C Language Support
    :id: FE_C_SUPPORT

docs/source/development/traceability.rst

@@ -12,5 +12,4 @@ Testing
 -------
 
 .. src-trace::
-   :project: sphinx_codelinks
-   :directory: tests
+   :project: tests

docs/src_trace.toml

@@ -61,3 +61,35 @@ needs_fields = [
   { "name" = "links", "type" = "list[str]", "default" = [
   ] },
 ]
+
+# Configuration for tests project
+[codelinks.projects.tests]
+remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit}/{path}#L{line}"
+
+[codelinks.projects.tests.source_discover]
+src_dir = "../tests"
+include = ["**/*.py"]
+exclude = [
+  "**/__pycache__/**",
+  "**/data/**",
+  "**/doc_test/**",
+  "**/__snapshots__/**",
+]
+comment_type = "python"
+gitignore = true
+
+[codelinks.projects.tests.analyse]
+get_need_id_refs = false
+get_oneline_needs = true
+comment_type = "python"
+
+[codelinks.projects.tests.analyse.oneline_comment_style]
+start_sequence = "@"
+field_split_char = ","
+needs_fields = [
+  { "name" = "title", "type" = "str" },
+  { "name" = "id", "type" = "str" },
+  { "name" = "type", "type" = "str", "default" = "test" },
+  { "name" = "links", "type" = "list[str]", "default" = [
+  ] },
+]

docs/ubproject.toml

@@ -37,7 +37,7 @@ style = "node"
 [[needs.types]]
 directive = "test"
 title = "Test"
-prefix = "T_"
+prefix = "TEST_"
 color = "#DarkTurquoise"
 style = "node"
 

src/sphinx_codelinks/analyse/analyse.py

@@ -127,6 +127,7 @@ def extract_marker(
                 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,
@@ -211,6 +212,7 @@ def extract_oneline_need(
             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 +260,7 @@ def extract_oneline_needs(
             )
         return oneline_needs
 
+    # @Extract marked reStructuredText blocks from comments, IMPL_MRST_1, impl, [FE_RST_EXTRACTION]
     def extract_marked_rst(
         self,
         text: str,

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:

src/sphinx_codelinks/analyse/utils.py

@@ -64,6 +64,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]
 def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
     if comment_type == CommentType.cpp:
         import tree_sitter_cpp  # noqa: PLC0415
@@ -100,6 +101,7 @@ def read_callable_byte_offset(byte_offset: int, _: Point) -> ByteString:
     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:
@@ -335,6 +337,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:

src/sphinx_codelinks/cmd.py

@@ -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)
 
@@ -183,6 +184,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 +236,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(

src/sphinx_codelinks/source_discover/source_discover.py

@@ -13,7 +13,7 @@
 )
 
 
-# @Source discovery, IMPL_DC_1, impl, [FE_DEF]
+# @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

tests/test_analyse.py

@@ -1,3 +1,4 @@
+# @Test suite for source code analysis and marker extraction, TEST_ANA_1, test, [IMPL_LNK_1, IMPL_ONE_1, IMPL_MRST_1]
 import json
 from pathlib import Path