From 4d867c05c1d13c843767e7f46ac1157860f94440 Mon Sep 17 00:00:00 2001 From: Patrick Dahlke Date: Fri, 14 Nov 2025 12:16:24 +0100 Subject: [PATCH 1/5] Add traceability --- docs/source/basics/quickstart.rst | 1 - docs/source/components/discover.rst | 1 - docs/source/components/features.rst | 297 ++++++++++++++++++ docs/source/components/oneline.rst | 1 - docs/source/components/write.rst | 16 +- docs/source/development/traceability.rst | 16 + docs/source/index.rst | 2 + docs/src_trace.toml | 26 ++ docs/ubproject.toml | 35 +++ src/sphinx_codelinks/analyse/utils.py | 2 + src/sphinx_codelinks/config.py | 7 + .../source_discover/source_discover.py | 1 + 12 files changed, 394 insertions(+), 11 deletions(-) create mode 100644 docs/source/components/features.rst create mode 100644 docs/source/development/traceability.rst diff --git a/docs/source/basics/quickstart.rst b/docs/source/basics/quickstart.rst index 96893cf..bf4779e 100644 --- a/docs/source/basics/quickstart.rst +++ b/docs/source/basics/quickstart.rst @@ -27,7 +27,6 @@ Sphinx Config :caption: src_trace.toml :language: toml - One-line comment ---------------- diff --git a/docs/source/components/discover.rst b/docs/source/components/discover.rst index db31c72..1e764f7 100644 --- a/docs/source/components/discover.rst +++ b/docs/source/components/discover.rst @@ -6,7 +6,6 @@ Source Discover SourceDiscover is one of the modules provided in ``Codelinks``. It discovers the source files from the given directory. It provides users CLI and API to discover the source files. - Usage Examples -------------- diff --git a/docs/source/components/features.rst b/docs/source/components/features.rst new file mode 100644 index 0000000..e596190 --- /dev/null +++ b/docs/source/components/features.rst @@ -0,0 +1,297 @@ +Features +======== + +.. dropdown:: 🔍 Features + + .. needtable:: + :filter: type == "feature" + :columns: id, title, si as "SI", parent_needs_back as "Errors" + +.. feature:: Define new traceability objects in source code + :id: FE_DEF + + Create new Sphinx-Needs directly from a single comment line in your source code. + This feature enables developers to maintain traceability information right at the point + of implementation, ensuring that requirements, specifications, and code remain synchronized. + + By embedding traceability markers in comments, you can: + + * Define requirements, specifications, or test cases directly in source files + * Automatically generate documentation from code comments + * Maintain bidirectional links between documentation and implementation + * Track coverage of requirements by implementation + + .. fault:: Traceability objects are not detected in supported languages + :id: FAULT_1 + + .. fault:: Sphinx-codelinks halucinates traceability objects + :id: FAULT_2 + +.. feature:: Discover Source Code Files + :id: FE_DISCOVERY + + Discover source code files in a specified root directory. The root directory shall be configurable. + +.. feature:: C Language Support + :id: FE_C_SUPPORT + + Support for defining traceability objects in C source code. + + The C language parser leverages tree-sitter to accurately identify and extract + comments from C source files, including both single-line (``//``) and multi-line + (``/* */``) comment styles. This ensures that traceability markers are correctly + associated with the appropriate code structures such as functions, structs, and + global definitions. + + Key capabilities: + + * Detection of inline and block comments + * Association of comments with function definitions + * Support for standard C comment conventions + * Accurate scope detection for nested structures + + .. fault:: Traceability objects are not detected in C language + :id: FAULT_C_1 + + .. fault:: Sphinx-codelinks halucinates traceability objects in C + :id: FAULT_C_2 + +.. feature:: C++ Language Support + :id: FE_CPP + + Support for defining traceability objects in C++ source code. + + Building upon C language support, the C++ parser handles the full complexity of modern + C++ syntax including classes, namespaces, templates, and advanced features. The tree-sitter + based parser ensures accurate comment extraction and scope detection across various C++ + constructs. + + Enhanced features for C++: + + * Class and namespace scope detection + * Support for C++ style comments (``//``) and C style comments (``/* */``) + * Template and method declaration handling + * Accurate association with member functions and constructors + * Support for modern C++ features (C++11/14/17/20) + + .. fault:: Traceability objects are not detected in C++ language + :id: FAULT_CPP_1 + + .. fault:: Sphinx-codelinks halucinates traceability objects in C++ + :id: FAULT_CPP_2 + +.. feature:: Python Language Support + :id: FE_PY + + Support for defining traceability objects in Python source code. + + The Python language parser provides comprehensive support for Python's unique comment + and docstring conventions. It can extract traceability markers from both standard + comments (``#``) and docstrings (triple-quoted strings), making it ideal for Python's + documentation-driven development practices. + + Python-specific capabilities: + + * Hash-style comment (``#``) detection + * Docstring extraction from modules, classes, and functions + * Proper handling of multi-line comments and docstrings + * Scope detection for functions, classes, and methods + * Support for nested class and function definitions + * Integration with Python's natural documentation patterns + + .. fault:: Traceability objects are not detected in Python language + :id: FAULT_PY_1 + + .. fault:: Sphinx-codelinks halucinates traceability objects in Python + :id: FAULT_PY_2 + +.. feature:: YAML Language Support + :id: FE_YAML + + Support for defining traceability objects in YAML configuration files. + + The YAML language parser provides comprehensive support for YAML's structure + and comment conventions. It can extract traceability markers from YAML comments + (``#``) and properly associate them with YAML structures including key-value pairs, + list items, and nested configurations, making it ideal for documenting configuration + files, CI/CD pipelines, and infrastructure definitions. + + YAML-specific capabilities: + + * Hash-style comment (``#``) detection + * Inline comment support with proper structure association + * Block comment detection and association + * Scope detection for block mapping pairs and sequence items + * Support for nested YAML structures + * Document structure handling with ``---`` separators + * Accurate association of inline comments with their corresponding structures + * Flow and block mapping/sequence support + + .. fault:: Traceability objects are not detected in YAML language + :id: FAULT_YAML_1 + + .. fault:: Sphinx-codelinks halucinates traceability objects in YAML + :id: FAULT_YAML_2 + +.. feature:: Customized comment styles + :id: FE_CMT + + Support for different customized comment styles in source code. + The comment structure can be defined in the configuration file. + + This feature provides flexibility to adapt Sphinx-Codelinks to your project's + existing coding standards and conventions. Define custom markers, prefixes, and + delimiters that match your team's documentation practices without requiring code + changes. + + Configuration options include: + + * Custom marker syntax (e.g., ``@req``, ``#TODO``, ``//!``) + * Configurable comment prefixes and delimiters + * Support for language-specific comment conventions + * Flexible pattern matching for traceability markers + * Per-project customization via configuration files + + .. fault:: Customized comment styles are not detected in supported languages + :id: FAULT_CMT + +.. feature:: Link code to existing need items + :id: FE_LNK + + Link code to existing need items without creating new ones, perfect for tracing + implementations to requirements. + + This feature enables you to establish connections between your source code and + existing documentation or requirements defined elsewhere in your Sphinx-Needs + documentation. Instead of creating duplicate need objects, you can simply reference + existing ones, maintaining a clean and organized traceability structure. + + Linking capabilities: + + * Reference existing requirements, specifications, or test cases by ID + * Create bidirectional links between code and documentation + * Avoid duplication of traceability information + * Support for multiple links from a single code location + * Automatic validation of link targets + * Integration with Sphinx-Needs link visualization + + .. fault:: Linking code to existing need items fails + :id: FAULT_LNK_1 + + .. fault:: Sphinx-codelinks links code to wrong need items + :id: FAULT_LNK_2 + +.. feature:: Extract blocks of reStructuredText embedded within comments + :id: FE_RST_EXTRACTION + + Extract blocks of reStructuredText embedded within comments, allowing you to + include rich documentation with associated metadata right next to your code. + + This powerful feature enables you to write full reStructuredText content directly + in your source code comments, which will be extracted and processed as part of + your Sphinx documentation. This approach brings documentation closer to implementation, + making it easier to keep both synchronized. + + reStructuredText extraction features: + + * Full reStructuredText syntax support within comments + * Extraction of formatted documentation blocks + * Support for directives, roles, and inline markup + * Preservation of indentation and formatting + * Integration with Sphinx-Needs directives + * Markers for block start (``@rst``) and end (``@endrst``) + * Single-line and multi-line RST blocks + + .. fault:: Extracting reStructuredText from comments fails + :id: FAULT_RST_EXTRACTION_1 + + .. fault:: Sphinx-codelinks extracts wrong reStructuredText blocks + :id: FAULT_RST_EXTRACTION_2 + + .. fault:: Extracted reStructuredText blocks are malformed + :id: FAULT_RST_EXTRACTION_3 + +.. feature:: Analyze marked content via CLI interface + :id: FE_CLI_ANALYZE + + It shall be possible to analyze marked content via the CLI interface. + + The command-line interface provides powerful tools for analyzing and reporting on + traceability markers in your codebase without requiring a full Sphinx build. This + enables quick validation, continuous integration checks, and standalone reporting. + + CLI analysis capabilities: + + * Scan source files for traceability markers + * Generate reports on found markers and their metadata + * Validate marker syntax and structure + * Export analysis results in various formats (JSON, CSV) + * Integration with CI/CD pipelines + * Fast iteration during development + * Batch processing of multiple files or directories + + .. fault:: CLI integration fails silently + :id: FAULT_CLI_ANALYZE_1 + + .. fault:: Sphinx-codelinks halucinates marked content + :id: FAULT_CLI_ANALYZE_2 + + .. fault:: Sphinx-codelinks misses marked content + :id: FAULT_CLI_ANALYZE_3 + +.. feature:: Discover the filepaths a specified root directory via CLI interface + :id: FE_CLI_DISCOVER + + It shall be possible to specify a root directory for the CLI interface. + All files in and below this directory shall be discovered. + + The discovery feature provides intelligent file system traversal to identify all + relevant source files within a project structure. This enables bulk operations + and ensures comprehensive coverage of your codebase. + + Discovery features: + + * Recursive directory traversal from specified root + * File type filtering based on extensions + * Respect for ignore patterns (e.g., ``.gitignore``) + * Detection of binary vs. text files + * Configurable include/exclude patterns + * Support for multiple root directories + * Efficient handling of large codebases + + .. fault:: Specifying a root directory fails + :id: FAULT_CLI_DISCOVER_1 + + .. fault:: Sphinx-codelinks discovers files outside the specified root directory + :id: FAULT_CLI_DISCOVER_2 + + Root directory setting is not respected or ignored + +.. feature:: Export marked content to other formats via CLI interface + :id: FE_CLI_WRITE + + It shall be possible to export marked content to other formats via the CLI interface. + + The export functionality enables transformation of extracted traceability data into + various output formats for use in external tools, reports, or downstream processing. + This makes Sphinx-Codelinks a versatile component in your documentation toolchain. + + Export capabilities: + + * JSON format for programmatic processing + * CSV format for spreadsheet analysis + * Sphinx-Needs compatible formats + * Custom format definitions via templates + * Batch export of multiple analyses + * Filtering and transformation options + * Integration with external reporting tools + * Support for incremental exports + + .. fault:: Exporting marked content fails + :id: FAULT_CLI_WRITE_1 + + .. fault:: Sphinx-codelinks exports wrong content + :id: FAULT_CLI_WRITE_2 + + .. fault:: Exported content is malformed + :id: FAULT_CLI_WRITE_3 diff --git a/docs/source/components/oneline.rst b/docs/source/components/oneline.rst index 8b0c470..5138f46 100644 --- a/docs/source/components/oneline.rst +++ b/docs/source/components/oneline.rst @@ -13,7 +13,6 @@ to simplify the effort required to create a need in source code. For more comprehensive examples and advanced configurations, see the `test cases `__. - Start and End sequences ----------------------- diff --git a/docs/source/components/write.rst b/docs/source/components/write.rst index 78d9ea3..1a962d4 100644 --- a/docs/source/components/write.rst +++ b/docs/source/components/write.rst @@ -34,16 +34,16 @@ The following RST file with :external+needs:ref:`needextend ` direct .. code-block:: rst - .. needextend:: NEED_001 - :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 + .. needextend:: NEED_001 + :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 - .. needextend:: NEED_002 - :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 + .. needextend:: NEED_002 + :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 - .. needextend:: NEED_003 - :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 + .. needextend:: NEED_003 + :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 - .. needextend:: NEED_004 - :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 + .. needextend:: NEED_004 + :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3 More examples can be found in `test cases `__ diff --git a/docs/source/development/traceability.rst b/docs/source/development/traceability.rst new file mode 100644 index 0000000..fc14d70 --- /dev/null +++ b/docs/source/development/traceability.rst @@ -0,0 +1,16 @@ +Traceability +============ + +Implementation +-------------- + +.. src-trace:: + :project: sphinx_codelinks + :directory: sphinx_codelinks + +Testing +------- + +.. src-trace:: + :project: sphinx_codelinks + :directory: tests diff --git a/docs/source/index.rst b/docs/source/index.rst index 94ff269..4b08562 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -66,6 +66,7 @@ Contents components/analyse components/discover components/write + components/features .. toctree:: :maxdepth: 1 @@ -74,3 +75,4 @@ Contents development/roadmap development/change_log development/contributing + development/traceability diff --git a/docs/src_trace.toml b/docs/src_trace.toml index cc7a6a3..6371e7f 100644 --- a/docs/src_trace.toml +++ b/docs/src_trace.toml @@ -35,3 +35,29 @@ remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit [codelinks.projects.src.source_discover] src_dir = "../tests/doc_test/minimum_config" + +# Configuration for source tracing project "sphinx_codelinks" +[codelinks.projects.sphinx_codelinks] +remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit}/{path}#L{line}" + +[codelinks.projects.sphinx_codelinks.source_discover] +src_dir = "../src" +include = ["**/*.py"] +comment_type = "python" +gitignore = true + +[codelinks.projects.sphinx_codelinks.analyse] +get_need_id_refs = false +get_oneline_needs = true +comment_type = "python" + +[codelinks.projects.sphinx_codelinks.analyse.oneline_comment_style] +start_sequence = "@" +field_split_char = "," +needs_fields = [ + { "name" = "title", "type" = "str" }, + { "name" = "id", "type" = "str" }, + { "name" = "type", "type" = "str", "default" = "impl" }, + { "name" = "links", "type" = "list[str]", "default" = [ + ] }, +] diff --git a/docs/ubproject.toml b/docs/ubproject.toml index a4e497b..6cb4cd2 100644 --- a/docs/ubproject.toml +++ b/docs/ubproject.toml @@ -6,6 +6,41 @@ ignore = ["block.title_line"] [needs] id_required = true +[[needs.types]] +directive = "feature" +title = "Feature" +prefix = "FEAT_" +color = "#Gold" +style = "rectangle" + +[[needs.types]] +directive = "usecase" +title = "Use Case" +prefix = "USE_" +color = "#Thistle" +style = "rectangle" + +[[needs.types]] +directive = "fault" +title = "Fault" +prefix = "FAULT_" +color = "#Pink" +style = "rectangle" + +[[needs.types]] +directive = "impl" +title = "Implementation" +prefix = "IMPL_" +color = "#LightGreen" +style = "node" + +[[needs.types]] +directive = "test" +title = "Test" +prefix = "T_" +color = "#DarkTurquoise" +style = "node" + [parse.extend_directives.src-trace] argument = false options = true diff --git a/src/sphinx_codelinks/analyse/utils.py b/src/sphinx_codelinks/analyse/utils.py index b69d35c..9793bdf 100644 --- a/src/sphinx_codelinks/analyse/utils.py +++ b/src/sphinx_codelinks/analyse/utils.py @@ -14,7 +14,9 @@ # 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"}, diff --git a/src/sphinx_codelinks/config.py b/src/sphinx_codelinks/config.py index 9f51422..c3fac2b 100644 --- a/src/sphinx_codelinks/config.py +++ b/src/sphinx_codelinks/config.py @@ -19,7 +19,9 @@ 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: ["//", "/*", "///"], } @@ -794,6 +796,9 @@ 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 + analyse_config_dict["comment_type"] = ( + src_discover.src_discover_config.comment_type + ) return SourceAnalyseConfig(**analyse_config_dict) @@ -856,4 +861,6 @@ 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 + analyse_config.comment_type = source_discover_config.comment_type project_config["analyse_config"] = analyse_config diff --git a/src/sphinx_codelinks/source_discover/source_discover.py b/src/sphinx_codelinks/source_discover/source_discover.py index 84c5563..7329a73 100644 --- a/src/sphinx_codelinks/source_discover/source_discover.py +++ b/src/sphinx_codelinks/source_discover/source_discover.py @@ -13,6 +13,7 @@ ) +# @Source discovery, IMPL_DC_1, impl, [FE_DEF] class SourceDiscover: def __init__(self, src_discover_config: SourceDiscoverConfig): self.src_discover_config = src_discover_config From e69009c0f8bdd44ee8b1a2b372011f7535d2b8c6 Mon Sep 17 00:00:00 2001 From: Patrick Dahlke Date: Fri, 14 Nov 2025 13:35:06 +0100 Subject: [PATCH 2/5] link impl and test suits/files --- docs/source/components/features.rst | 3 +- docs/source/development/traceability.rst | 3 +- docs/src_trace.toml | 32 +++++++++++++++++++ docs/ubproject.toml | 2 +- src/sphinx_codelinks/analyse/analyse.py | 3 ++ .../analyse/oneline_parser.py | 1 + src/sphinx_codelinks/analyse/utils.py | 3 ++ src/sphinx_codelinks/cmd.py | 3 ++ .../source_discover/source_discover.py | 2 +- tests/test_analyse.py | 1 + tests/test_analyse_config.py | 1 + tests/test_analyse_utils.py | 1 + tests/test_cmd.py | 1 + tests/test_needextend_write.py | 1 + tests/test_oneline_parser.py | 1 + tests/test_source_discover.py | 1 + tests/test_src_trace.py | 1 + 17 files changed, 55 insertions(+), 5 deletions(-) diff --git a/docs/source/components/features.rst b/docs/source/components/features.rst index e596190..61f2a08 100644 --- a/docs/source/components/features.rst +++ b/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 diff --git a/docs/source/development/traceability.rst b/docs/source/development/traceability.rst index fc14d70..a6cb424 100644 --- a/docs/source/development/traceability.rst +++ b/docs/source/development/traceability.rst @@ -12,5 +12,4 @@ Testing ------- .. src-trace:: - :project: sphinx_codelinks - :directory: tests + :project: tests diff --git a/docs/src_trace.toml b/docs/src_trace.toml index 6371e7f..a439f57 100644 --- a/docs/src_trace.toml +++ b/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" = [ + ] }, +] diff --git a/docs/ubproject.toml b/docs/ubproject.toml index 6cb4cd2..11fe754 100644 --- a/docs/ubproject.toml +++ b/docs/ubproject.toml @@ -37,7 +37,7 @@ style = "node" [[needs.types]] directive = "test" title = "Test" -prefix = "T_" +prefix = "TEST_" color = "#DarkTurquoise" style = "node" diff --git a/src/sphinx_codelinks/analyse/analyse.py b/src/sphinx_codelinks/analyse/analyse.py index 79bc051..a8e9751 100644 --- a/src/sphinx_codelinks/analyse/analyse.py +++ b/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, diff --git a/src/sphinx_codelinks/analyse/oneline_parser.py b/src/sphinx_codelinks/analyse/oneline_parser.py index 13c9270..2e993db 100644 --- a/src/sphinx_codelinks/analyse/oneline_parser.py +++ b/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: diff --git a/src/sphinx_codelinks/analyse/utils.py b/src/sphinx_codelinks/analyse/utils.py index 9793bdf..d9c6dab 100644 --- a/src/sphinx_codelinks/analyse/utils.py +++ b/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: diff --git a/src/sphinx_codelinks/cmd.py b/src/sphinx_codelinks/cmd.py index bc0077f..a702414 100644 --- a/src/sphinx_codelinks/cmd.py +++ b/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( diff --git a/src/sphinx_codelinks/source_discover/source_discover.py b/src/sphinx_codelinks/source_discover/source_discover.py index 7329a73..d7200cd 100644 --- a/src/sphinx_codelinks/source_discover/source_discover.py +++ b/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 diff --git a/tests/test_analyse.py b/tests/test_analyse.py index d9897cc..43ea83b 100644 --- a/tests/test_analyse.py +++ b/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 diff --git a/tests/test_analyse_config.py b/tests/test_analyse_config.py index 7c81d5d..166d5a6 100644 --- a/tests/test_analyse_config.py +++ b/tests/test_analyse_config.py @@ -1,3 +1,4 @@ +# @Test suite for source analysis configuration validation, TEST_CONF_1, test, [IMPL_OLP_1] import pytest from sphinx_codelinks.config import OneLineCommentStyle, SourceAnalyseConfig diff --git a/tests/test_analyse_utils.py b/tests/test_analyse_utils.py index 1b6fbd4..c9a8b4c 100644 --- a/tests/test_analyse_utils.py +++ b/tests/test_analyse_utils.py @@ -1,3 +1,4 @@ +# @Test suite for tree-sitter parsing utilities and language support, TEST_LANG_1, test, [IMPL_LANG_1, IMPL_EXTR_1, IMPL_RST_1] from pathlib import Path import shutil import subprocess diff --git a/tests/test_cmd.py b/tests/test_cmd.py index 60a4c2e..4222dca 100644 --- a/tests/test_cmd.py +++ b/tests/test_cmd.py @@ -1,3 +1,4 @@ +# @Test suite for CLI commands including analyse, discover, and write, TEST_CLI_1, test, [IMPL_CLI_ANALYZE, IMPL_CLI_DISCOVER, IMPL_CLI_WRITE] import json from pathlib import Path diff --git a/tests/test_needextend_write.py b/tests/test_needextend_write.py index 4a2342e..580c627 100644 --- a/tests/test_needextend_write.py +++ b/tests/test_needextend_write.py @@ -1,3 +1,4 @@ +# @Test suite for needextend RST generation from extracted markers, TEST_WRITE_1, test, [IMPL_CLI_WRITE] import pytest from sphinx_codelinks.needextend_write import convert_marked_content diff --git a/tests/test_oneline_parser.py b/tests/test_oneline_parser.py index aa4ef91..e0e55a3 100644 --- a/tests/test_oneline_parser.py +++ b/tests/test_oneline_parser.py @@ -1,3 +1,4 @@ +# @Test suite for one-line comment parser functionality, TEST_OLP_1, test, [IMPL_OLP_1] import pytest from sphinx_codelinks.analyse.oneline_parser import ( diff --git a/tests/test_source_discover.py b/tests/test_source_discover.py index a71bb62..1fdfe8b 100644 --- a/tests/test_source_discover.py +++ b/tests/test_source_discover.py @@ -1,3 +1,4 @@ +# @Test suite for source file discovery with gitignore support, TEST_DISC_1, test, [IMPL_DISC_1] from pathlib import Path import pytest diff --git a/tests/test_src_trace.py b/tests/test_src_trace.py index 519eb80..91067c5 100644 --- a/tests/test_src_trace.py +++ b/tests/test_src_trace.py @@ -1,3 +1,4 @@ +# @Test suite for Sphinx extension source tracing functionality, TEST_EXT_1, test, [IMPL_LNK_1, IMPL_ONE_1, IMPL_MRST_1] from collections.abc import Callable from pathlib import Path import shutil From 9d937ce558e5796d04c67f66c0111276730444ae Mon Sep 17 00:00:00 2001 From: Patrick Dahlke Date: Mon, 24 Nov 2025 23:44:05 +0000 Subject: [PATCH 3/5] Fix mypy --- src/sphinx_codelinks/config.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/sphinx_codelinks/config.py b/src/sphinx_codelinks/config.py index c3fac2b..b043168 100644 --- a/src/sphinx_codelinks/config.py +++ b/src/sphinx_codelinks/config.py @@ -796,7 +796,7 @@ 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 - analyse_config_dict["comment_type"] = ( + analyse_config_dict["comment_type"] = CommentType( src_discover.src_discover_config.comment_type ) @@ -862,5 +862,5 @@ 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 - analyse_config.comment_type = source_discover_config.comment_type + analyse_config.comment_type = CommentType(source_discover_config.comment_type) project_config["analyse_config"] = analyse_config From dda93aaea7ce941c94401ad5bfff6b654bb50f4a Mon Sep 17 00:00:00 2001 From: Patrick Dahlke Date: Mon, 24 Nov 2025 23:52:16 +0000 Subject: [PATCH 4/5] fix ci --- src/sphinx_codelinks/config.py | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/src/sphinx_codelinks/config.py b/src/sphinx_codelinks/config.py index b043168..24e412f 100644 --- a/src/sphinx_codelinks/config.py +++ b/src/sphinx_codelinks/config.py @@ -796,9 +796,16 @@ 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 - analyse_config_dict["comment_type"] = CommentType( - src_discover.src_discover_config.comment_type - ) + 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 + analyse_config_dict["comment_type"] = ( + src_discover.src_discover_config.comment_type + ) # type: ignore[typeddict-item] return SourceAnalyseConfig(**analyse_config_dict) @@ -862,5 +869,12 @@ 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 - analyse_config.comment_type = CommentType(source_discover_config.comment_type) + 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 From 2492b90079d382d0a81e760182bdd06d85501a8c Mon Sep 17 00:00:00 2001 From: Patrick Dahlke Date: Mon, 24 Nov 2025 23:58:51 +0000 Subject: [PATCH 5/5] Fix mypy --- src/sphinx_codelinks/config.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/sphinx_codelinks/config.py b/src/sphinx_codelinks/config.py index 24e412f..3aac458 100644 --- a/src/sphinx_codelinks/config.py +++ b/src/sphinx_codelinks/config.py @@ -803,9 +803,8 @@ def convert_analyse_config( except ValueError: # If invalid comment_type, keep the string value # Validation will catch this error later - analyse_config_dict["comment_type"] = ( - src_discover.src_discover_config.comment_type - ) # type: ignore[typeddict-item] + 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)