Merge pull request #2519 from strictdoc-project/stanislaw/section_filter

feat(export/html): remove legacy --filter-sections, rename: --filter-requirements -> --filter-nodes

Author: stanislaw

docs/strictdoc_01_user_guide.sdoc

@@ -3809,15 +3809,15 @@ TITLE: Filtering content
 [TEXT]
 MID: d52d86750ad54ce1b3263ebb092451c0
 STATEMENT: >>>
-Both ``export`` command-line interface commands support filtering documentation content with ``--filter-requirements`` and ``--filter-sections`` options.
+The ``export`` command-line interface command supports filtering documentation content with the ``--filter-nodes`` option.
 
-Both options are based on the Query Engine, so the same rules that are valid for Search also apply for filtering. When a filter is applied, only the whitelisted requirements/sections will be exported.
+The option is based on the Query Engine, so the same rules that are valid for Search also apply for filtering. When a filter is applied, only the whitelisted nodes will be exported.
 
 Example:
 
 .. code-block::
 
-    strictdoc export . --filter-requirements '"System" in node["TITLE"]'
+    strictdoc export . --filter-nodes '"System" in node["TITLE"]'
 <<<
 
 [[/SECTION]]

strictdoc/cli/cli_arg_parser.py

@@ -137,8 +137,7 @@ def __init__(
         no_parallelization: bool,
         enable_mathjax: bool,
         included_documents: bool,
-        filter_requirements: Optional[str],
-        filter_sections: Optional[str],
+        filter_nodes: Optional[str],
         reqif_profile: Optional[str],
         reqif_multiline_is_xhtml: bool,
         reqif_enable_mid: bool,
@@ -156,8 +155,7 @@ def __init__(
         self.no_parallelization: bool = no_parallelization
         self.enable_mathjax: bool = enable_mathjax
         self.included_documents: bool = included_documents
-        self.filter_requirements: Optional[str] = filter_requirements
-        self.filter_sections: Optional[str] = filter_sections
+        self.filter_nodes: Optional[str] = filter_nodes
         self.reqif_profile: Optional[str] = reqif_profile
         self.reqif_multiline_is_xhtml: bool = reqif_multiline_is_xhtml
         self.reqif_enable_mid: bool = reqif_enable_mid
@@ -281,8 +279,7 @@ def get_export_config(self) -> ExportCommandConfig:
             self.args.no_parallelization,
             self.args.enable_mathjax,
             self.args.included_documents,
-            self.args.filter_requirements,
-            self.args.filter_sections,
+            self.args.filter_nodes,
             self.args.reqif_profile,
             self.args.reqif_multiline_is_xhtml,
             self.args.reqif_enable_mid,

strictdoc/cli/command_parser_builder.py

@@ -238,16 +238,14 @@ def add_export_command(
                 "SPEC-OBJECT's IDENTIFIER and vice versa when exporting/importing."
             ),
         )
+        # FIXME: --filter-requirements will be removed in 2026.
         command_parser_export.add_argument(
+            "--filter-nodes",
             "--filter-requirements",
+            dest="filter_nodes",
             type=str,
             help="Filter which requirements will be exported.",
         )
-        command_parser_export.add_argument(
-            "--filter-sections",
-            type=str,
-            help="Filter which sections will be exported.",
-        )
         command_parser_export.add_argument(
             "--view",
             type=str,
@@ -429,16 +427,14 @@ def add_passthrough_command(
             type=str,
             help="A directory where to output the SDoc files to.",
         )
+        # FIXME: --filter-requirements will be removed in 2026.
         command_parser_passthrough.add_argument(
+            "--filter-nodes",
             "--filter-requirements",
+            dest="filter_nodes",
             type=str,
             help="Filter which requirements will be exported.",
         )
-        command_parser_passthrough.add_argument(
-            "--filter-sections",
-            type=str,
-            help="Filter which sections will be exported.",
-        )
         command_parser_passthrough.add_argument(
             "--view",
             type=str,

strictdoc/core/project_config.py

@@ -206,8 +206,7 @@ def __init__(
         self.export_formats: Optional[List[str]] = None
         self.export_included_documents: bool = False
         self.generate_bundle_document: bool = False
-        self.filter_requirements: Optional[str] = None
-        self.filter_sections: Optional[str] = None
+        self.filter_nodes: Optional[str] = None
 
         self.excel_export_fields: Optional[List[str]] = None
 
@@ -327,8 +326,7 @@ def integrate_export_config(
         self.export_formats = export_config.formats
         self.export_included_documents = export_config.included_documents
         self.generate_bundle_document = export_config.generate_bundle_document
-        self.filter_requirements = export_config.filter_requirements
-        self.filter_sections = export_config.filter_sections
+        self.filter_nodes = export_config.filter_nodes
         self.excel_export_fields = export_config.fields
         self.view = export_config.view
         self.chromedriver = export_config.chromedriver

strictdoc/core/traceability_index_builder.py

@@ -802,71 +802,64 @@ def child_cycle_traverse_(node_id: str) -> Any:
     def _filter_nodes(
         project_config: ProjectConfig, traceability_index: TraceabilityIndex
     ) -> None:
-        if (
-            project_config.filter_requirements is not None
-            or project_config.filter_sections is not None
-        ):
-            query_reader = QueryReader()
-            requirements_query_object: Union[QueryObject, QueryNullObject]
-            try:
-                if project_config.filter_requirements is not None:
-                    requirements_query = query_reader.read(
-                        project_config.filter_requirements
-                    )
-                    requirements_query_object = QueryObject(
-                        requirements_query, traceability_index
-                    )
-                else:
-                    requirements_query_object = QueryNullObject()
-            except TextXSyntaxError:
-                # FIXME: This must throw a StrictDocException.
-                print("error: Cannot parse filter query.")  # noqa: T201
-                sys.exit(1)
-            try:
-                for document in traceability_index.document_tree.document_list:
-                    document_iterator = (
-                        traceability_index.get_document_iterator(document)
-                    )
-                    for node, _ in document_iterator.all_content():
+        if project_config.filter_nodes is None:
+            return
+
+        query_reader = QueryReader()
+        requirements_query_object: Union[QueryObject, QueryNullObject]
+        try:
+            requirements_query = query_reader.read(project_config.filter_nodes)
+            requirements_query_object = QueryObject(
+                requirements_query, traceability_index
+            )
+        except TextXSyntaxError as textx_syntax_error_:
+            raise StrictDocException(
+                "Cannot parse filter query."
+            ) from textx_syntax_error_
+
+        try:
+            for document in traceability_index.document_tree.document_list:
+                document_iterator = traceability_index.get_document_iterator(
+                    document
+                )
+                for node, _ in document_iterator.all_content():
+                    if (
+                        isinstance(node, SDocNode)
+                        and node.node_type == "SECTION"
+                        and not requirements_query_object.evaluate(node)
+                    ):
+                        node.ng_whitelisted = False
+                        # If the node is the last one, we check if all other
+                        # nodes are filtered out and if so, mark the parent
+                        # section node as not whitelisted as well.
                         if (
-                            isinstance(node, SDocNode)
-                            and node.node_type == "SECTION"
-                            and not requirements_query_object.evaluate(node)
+                            node.parent.section_contents[
+                                len(node.parent.section_contents) - 1
+                            ]
+                            == node
                         ):
-                            node.ng_whitelisted = False
-                            # If the node is the last one, we check if all other
-                            # nodes are filtered out and if so, mark the parent
-                            # section node as not whitelisted as well.
                             if (
-                                node.parent.section_contents[
-                                    len(node.parent.section_contents) - 1
-                                ]
-                                == node
-                            ):
-                                if (
-                                    isinstance(node.parent, SDocNode)
-                                    and node.parent.node_type == "SECTION"
-                                ):
-                                    node.parent.blacklist_if_needed()
-
-                        elif isinstance(
-                            node, SDocNode
-                        ) and not requirements_query_object.evaluate(node):
-                            node.ng_whitelisted = False
-                            # If the node is the last one, we check if all other
-                            # nodes are filtered out and if so, mark the parent
-                            # section node as not whitelisted as well.
-                            if (
-                                node.parent.section_contents[
-                                    len(node.parent.section_contents) - 1
-                                ]
-                                == node
+                                isinstance(node.parent, SDocNode)
+                                and node.parent.node_type == "SECTION"
                             ):
                                 node.parent.blacklist_if_needed()
 
-            except (AttributeError, NameError, TypeError) as attribute_error_:
-                print(  # noqa: T201
-                    "error: cannot apply a filter query to a node: "
-                    f"{attribute_error_}"
-                )
-                sys.exit(1)
+                    elif isinstance(
+                        node, SDocNode
+                    ) and not requirements_query_object.evaluate(node):
+                        node.ng_whitelisted = False
+                        # If the node is the last one, we check if all other
+                        # nodes are filtered out and if so, mark the parent
+                        # section node as not whitelisted as well.
+                        if (
+                            node.parent.section_contents[
+                                len(node.parent.section_contents) - 1
+                            ]
+                            == node
+                        ):
+                            node.parent.blacklist_if_needed()
+
+        except (AttributeError, NameError, TypeError) as attribute_error_:
+            raise StrictDocException(
+                f"Cannot apply a filter query to a node: {attribute_error_}"
+            ) from attribute_error_

tests/integration/features/html/--filter-requirements/01_basic_filter/input.sdoc renamed to tests/integration/features/html/--filter-nodes/01_basic_filter/input.sdoc

@@ -1,4 +1,6 @@
 RUN: %strictdoc export %S --output-dir %T --filter-requirements='("2" in node["TITLE"] or "4" in node["TITLE"])' | filecheck %s --dump-input=fail
+RUN: rm -rf %T/*
+RUN: %strictdoc export %S --output-dir %T --filter-nodes='("2" in node["TITLE"] or "4" in node["TITLE"])' | filecheck %s --dump-input=fail
 CHECK: Published: Hello world doc
 
 RUN: %cat %T/html/index.html | filecheck %s --dump-input=fail --check-prefix CHECK-HTML

tests/integration/features/html/--filter-requirements/01_basic_filter/test.itest renamed to tests/integration/features/html/--filter-nodes/01_basic_filter/test.itest

@@ -1,4 +1,4 @@
-RUN: %strictdoc export %S --output-dir %T --filter-requirements='("1" in node["TITLE"] or "2" in node["TITLE"])' | filecheck %s --dump-input=fail
+RUN: %strictdoc export %S --output-dir %T --filter-nodes='("1" in node["TITLE"] or "2" in node["TITLE"])' | filecheck %s --dump-input=fail
 CHECK: Published: Hello world doc
 
 RUN: %cat %T/html/index.html | filecheck %s --dump-input=fail --check-prefix CHECK-HTML