adapt comments

Author: juiwenchen

docs/source/components/directive.rst

@@ -3,7 +3,7 @@
 Directive
 =========
 
-.. attention:: ``src-trace`` directive do NOT supports :ref:`Sphinx-Needs ID Refs <analyse_need_id_refs>`.
+.. attention:: ``src-trace`` directive does NOT support :ref:`Sphinx-Needs ID Refs <analyse_need_id_refs>`.
 
 ``src-trace`` Directive generates Sphinx-Needs items from source code comments. There are two ways to define need items in source code:
 

docs/source/components/rst_parser.rst

@@ -1,11 +1,17 @@
-Simplified reStructuredText Parser
-==================================
+RST directive Parser
+====================
 
 The :ref:`analyse <analyse>` module provides a simplified parser for reStructuredText (reST) directives using the ``Lark`` parsing library.
 It is designed to only parse the RST text extracted by :ref:`RST markers <analyse_rst>`, focusing on specific directive types and their associated options and content.
 By doing so, the parser avoids the complexity of a full reST parser while still capturing the essential structure needed for Sphinx-Needs integration from the source code.
 
-The parser does't have the Sphinx-Needs directive validation logic. It only checks the syntax of the RST directives and extracts the directive type, argument, options, and content.
+The parser doesn't have the Sphinx-Needs directive validation logic. It only checks the syntax of the RST directives and extracts:
+   - directive type
+   - argument (title)
+   - options
+   - content
+
+These extracted data will be furthered used with :external+needs:ref:`add_need <api>` function to create Sphinx-Needs items in ``src-trace`` directive.
 
 **Limitations**
 

docs/source/development/change_log.rst

@@ -17,7 +17,7 @@ New and Improved
   The resolved RST blocks will be dumped into the JSON output along with other extracted markers.
   To make the parser more stable, 3 new configuration options are added to control the parsing behavior:
 
-  - ``leading_sequences``: List of leading character sequences to strip from each line.
+  - ``strip_leading_sequences``: List of leading character sequences to strip from each line.
 
     This option allows users to specify a list of leading character sequences (e.g., ``*``, ``-``) that should be stripped
     from each line of the marked RST block before parsing.

src/sphinx_codelinks/analyse/analyse.py

@@ -337,7 +337,7 @@ def extract_marked_rst(
                 "column": end_column,
             },
         }
-        need_directive: None | NeedDirectiveType | UnexpectedInput = None
+        need_directive: None | NeedDirectiveType | UnexpectedInput
         need_directive = parse_rst(
             rst_text, self.analyse_config.marked_rst_config.indented_spaces
         )
@@ -358,7 +358,7 @@ def extract_marked_rst(
                     and isinstance(val, str)
                 ):
                     # convert link options values to list
-                    resolved[key] = val.split(",")
+                    resolved[key] = [item.strip() for item in val.split(",")]
                 else:
                     resolved[key] = val
 

src/sphinx_codelinks/analyse/sn_rst_parser.py

@@ -1,7 +1,11 @@
-"""Test script for RST directive Lark parser."""
+"""Parse reStructuredText (RST) directives using the Lark parser.
+
+This module provides functionality to parse RST directive blocks and extract their components,
+such as directive type, title, options, and content for further use by add_need() in src-trace directive.
+"""
 
 # ruff: noqa: N802
-# TODO: Not sure Lark is the right tool for this job since the it has a few limitations such as lack of support for dynamic indentation levels while extracting leading spaces in content.
+# TODO: Not sure Lark is the right tool for this job since it has a few limitations such as lack of support for dynamic indentation levels while extracting leading spaces in content.
 # Consider switching to Visitor instead of Transformer to have more control on resolving the tree or implement a custom parser if needed.
 
 from typing import TypedDict
@@ -11,10 +15,6 @@
 from sphinx_codelinks.config import UNIX_NEWLINE
 
 
-class PreProcessError(Exception):
-    """Custom error for preprocess issues."""
-
-
 class NeedDirectiveType(TypedDict, total=False):
     type: str
     title: str | None
@@ -66,7 +66,7 @@ def content_line(self, *line):
             return line[1].rstrip()
 
     def content_block(self, *lines):
-        # items is list of lines
+        # items are list of lines
         return {"content": "\n".join(lines)}
 
     def directive_block(self, *blocks):
@@ -75,7 +75,7 @@ def directive_block(self, *blocks):
     def directive(self, name, *optionals):
         # NAME,, optional title/options/content
         need = {"type": name}
-        # flaten optionals
+        # flatten optionals
         flatten_optionals: list[dict[str, str]] = []
         for item in optionals:
             if isinstance(item, tuple):
@@ -157,8 +157,8 @@ def preprocess_rst(text: str) -> str:
     """Process valid RST directive text before parsing.
 
     The followings are processed:
-    - Stripe leading spaces before the directive marker to get relative indentations.
-    - Stripe trailing spaces at the end
+    - Strip leading spaces before the directive marker to get relative indentations.
+    - Strip trailing spaces at the end
     - Ensure the text ends with a newline.
     """
     if not text:

tests/fixture_files/analyse_rst.yml

@@ -68,21 +68,6 @@ link_options_rst_marker:
       return 0;
     }
 
-link_options_rst_marker:
-  dummy_1.c: |
-    /*
-     * @rst
-     * .. impl:: implement main function
-     *    :id: REQ_001
-     *    :links: IMPL_001, IMPL_002
-     *
-     *    This is content for the main function implementation.
-     * @endrst
-    */
-    int main() {
-      return 0;
-    }
-
 warning_invalid_type:
   dummy_1.c: |
     /*