Merge pull request #2522 from strictdoc-project/stanislaw/remove_sdoc_marker

chore(backend/sdoc_source_code): remove legacy @sdoc/nosdoc

Author: stanislaw

developer/fixit/check_comments.py

@@ -14,7 +14,6 @@
     "pragma",
     "pylint",
     "@relation",
-    "@sdoc",
     "type:",
 ]
 

docs/strictdoc_01_user_guide.sdoc

@@ -2735,10 +2735,6 @@ To connect a source file to a requirement, a dedicated ``@relation`` marker must
 
     For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see [LINK: SECTION-UG-Language-aware-parsing-of-source-code].
 
-.. warning::
-
-    The legacy ``@sdoc`` marker is still supported by StrictDoc but is deprecated. ``@relation`` is the new correct marker name.
-
 It is also possible to use @relation markers and be compatible with Doxygen. See [LINK: SECTION-UG-Doxygen].
 
 **1\) Linking a file to a requirement**
@@ -2930,6 +2926,28 @@ To establish a backward link from a source file to an SDoc node:
 
 [[/SECTION]]
 
+[[SECTION]]
+MID: b893f545d95d457e8366928c467a2f5d
+TITLE: Ignoring source code markers
+
+[TEXT]
+MID: 5c9881f6fa2847b3b95ef0cad131cfb3
+STATEMENT: >>>
+Sometimes, it is necessary to ignore ``@relation(...)`` markers in a specific section of a file. This can be done using the special skip keyword, as shown below:
+
+.. code-block::
+
+    # @relation(skip, scope=range_start)
+    # @relation(REQ-001, scope=range_start)
+    ...
+    # @relation(REQ-001, scope=range_end)
+    # @relation(skip, scope=range_end)
+
+In this example, the ``skip``-relation causes StrictDoc to ignore the ``REQ-001`` requirement, so that it does not appear in the traceability information.
+<<<
+
+[[/SECTION]]
+
 [[SECTION]]
 MID: c9da7df725564208971e7ee058ad8d73
 UID: SECTION-UG-Parsing-SDoc-source-nodes

docs/strictdoc_04_release_notes.sdoc

@@ -52,7 +52,9 @@ TITLE: Unreleased
 [TEXT]
 MID: 12345f3b28ea4bfe9ca8afe6b21826a8
 STATEMENT: >>>
-This release includes several bug fixes and improvements for edge cases.
+This release includes the removal of legacy @sdoc markers, several bug fixes, and enhancements for edge cases.
+
+The legacy ``@sdoc`` marker has been removed from the codebase. From now on, only the ``@relation`` markers are recognized when linking requirements with source code files.
 
 An edge case has been fixed where StrictDoc’s FileFinder was detecting Linux pipe files that could not be processed meaningfully by StrictDoc’s source file generator. With this release, such files are now ignored.
 

pyproject.toml

@@ -47,7 +47,7 @@ classifiers = [
     "Programming Language :: Python :: Implementation :: PyPy",
 ]
 
-# @sdoc[SDOC-SRS-89]
+# @relation(SDOC-SRS-89, scope=range_start)
 dependencies = [
     "textx >= 4.0.0, == 4.*",
     "lark >= 1.2.2",
@@ -104,7 +104,7 @@ dependencies = [
     "plotly",
     "pandas"
 ]
-# @sdoc[/SDOC-SRS-89]
+# @relation(SDOC-SRS-89, scope=range_end)
 
 [project.optional-dependencies]
 development = [

strictdoc/backend/sdoc_source_code/grammar.py

@@ -17,20 +17,12 @@
 ;
 
 RangeMarker[noskipws]:
-  // It is a hard-won result: it is important that the "@sdoc" is within the
-  // regex. Putting it next to the regex as "@sdoc" does not work.
+  // It is a hard-won result: it is important that the "@relation" is within the
+  // regex. Putting it next to the regex as "@relation" does not work.
   // TODO: It would be great to check this with the TextX developers.
-  (
-  /^.*?@sdoc/
-  (begin_or_end = "[/" | begin_or_end = "[")
-  (reqs_objs += Req[', ']) ']' '\n'?
-  )
-  |
-  (
   /^.*?@relation/
   '('
   (reqs_objs += Req[', ']) ', scope=' scope=/(range_start|range_end)/ (", role=" role=/{REGEX_ROLE}/)? ')' '\n'?
-  )
 ;
 
 FunctionRangeMarker[noskipws]:
@@ -39,18 +31,12 @@
 ;
 
 LineMarker[noskipws]:
-  // It is a hard-won result: it is important that the "@sdoc" is within the
-  // regex. Putting it next to the regex as "@sdoc" does not work.
+  // It is a hard-won result: it is important that the "@relation" is within the
+  // regex. Putting it next to the regex as "@relation" does not work.
   // TODO: It would be great to check this with the TextX developers.
-  (
-  /^.*?@sdoc/
-  "(" (reqs_objs += Req[', ']) ')' '\n'?
-  )
-  |
-  (
+
   /^.*?@relation/
   "(" (reqs_objs += Req[', ']) ', scope=line' (", role=" role=/{REGEX_ROLE}/)? ")" '\n'?
-  )
 ;
 
 Req[noskipws]:

strictdoc/backend/sdoc_source_code/marker_parser.py

@@ -163,11 +163,10 @@ def _parse_relation_marker(
                 function_marker.set_description(f"class {entity_name}")
             markers.append(function_marker)
         elif relation_scope in ("range_start", "range_end"):
-            start_or_end = relation_scope == "range_start"
             range_marker = RangeMarker(
                 None,
-                "[" if start_or_end else "[/",
                 requirements,
+                scope=relation_scope,
                 role=relation_role,
             )
             range_marker.ng_source_line_begin = (
@@ -178,7 +177,6 @@ def _parse_relation_marker(
             )
             range_marker.ng_range_line_begin = line_start
             range_marker.ng_range_line_end = line_end
-            range_marker.ng_new_relation_keyword = True
             markers.append(range_marker)
         elif relation_scope == "line":
             line_marker = LineMarker(None, requirements, role=relation_role)

strictdoc/backend/sdoc_source_code/models/function_range_marker.py

@@ -50,7 +50,7 @@ def __init__(
         self.ng_marker_line: Optional[int] = None
         self.ng_marker_column: Optional[int] = None
 
-        self.ng_is_nodoc = "nosdoc" in self.reqs
+        self.ng_is_nodoc = "skip" in self.reqs
 
         self.begin_or_end: bool = True
 

strictdoc/backend/sdoc_source_code/models/line_marker.py

@@ -28,7 +28,7 @@ def __init__(
         self.ng_range_line_begin: Optional[int] = None
         self.ng_range_line_end: Optional[int] = None
 
-        self.ng_is_nodoc: bool = "nosdoc" in self.reqs
+        self.ng_is_nodoc: bool = "skip" in self.reqs
         self.begin_or_end = True
 
     def is_begin(self) -> bool:

strictdoc/backend/sdoc_source_code/models/range_marker.py

@@ -13,22 +13,15 @@ class RangeMarker:
     def __init__(
         self,
         parent: Any,
-        begin_or_end: str,
         reqs_objs: List[Req],
         scope: str = "",
         role: Optional[str] = None,
     ) -> None:
         assert isinstance(reqs_objs, list)
         self.parent: Any = parent
-        assert len(begin_or_end) > 0 or scope is not None
 
-        self.begin_or_end: str
-        if len(begin_or_end) > 0:
-            self.begin_or_end = begin_or_end
-        else:
-            assert scope in ("range_start", "range_end")
-            self.begin_or_end = "[" if scope == "range_start" else "[/"
-            self.ng_new_relation_keyword = True
+        assert scope in ("range_start", "range_end")
+        self.begin_or_end: bool = scope == "range_start"
 
         self.reqs_objs: List[Req] = reqs_objs
         self.reqs: List[str] = list(map(lambda req: req.uid, reqs_objs))
@@ -51,14 +44,13 @@ def __init__(
         self.ng_range_line_begin: Optional[int] = None
         self.ng_range_line_end: Optional[int] = None
 
-        self.ng_is_nodoc: bool = "nosdoc" in self.reqs
-        self.ng_new_relation_keyword = scope is not None and len(scope) > 0
+        self.ng_is_nodoc: bool = "skip" in self.reqs
 
     def is_begin(self) -> bool:
-        return self.begin_or_end == "["
+        return self.begin_or_end
 
     def is_end(self) -> bool:
-        return self.begin_or_end == "[/"
+        return not self.begin_or_end
 
     def is_range_marker(self) -> bool:
         return True

strictdoc/backend/sdoc_source_code/parse_context.py

@@ -2,8 +2,12 @@
 @relation(SDOC-SRS-33, scope=file)
 """
 
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
+from strictdoc.backend.sdoc_source_code.models.function_range_marker import (
+    FunctionRangeMarker,
+)
+from strictdoc.backend.sdoc_source_code.models.line_marker import LineMarker
 from strictdoc.backend.sdoc_source_code.models.range_marker import RangeMarker
 from strictdoc.helpers.file_stats import SourceFileStats
 
@@ -12,8 +16,10 @@ class ParseContext:
     def __init__(
         self, filename: Optional[str], file_stats: SourceFileStats
     ) -> None:
-        self.filename: Optional[str] = filename
+        self.filename: str = filename if filename else "<no filename>"
         self.file_stats: SourceFileStats = file_stats
         self.markers: List[Any] = []
-        self.marker_stack: List[RangeMarker] = []
+        self.marker_stack: List[
+            Union[RangeMarker, FunctionRangeMarker, LineMarker]
+        ] = []
         self.map_reqs_to_markers: Dict[str, Any] = {}