🔧 Add remove_node_from_tree utility function (#1063)

Just de-duplicates some logic used in multiple places

sphinx_needs/directives/need.py

@@ -17,11 +17,7 @@
 from sphinx_needs.data import NeedsInfoType, SphinxNeedsData
 from sphinx_needs.debug import measure_time
 from sphinx_needs.defaults import NEED_DEFAULT_OPTIONS
-from sphinx_needs.directives.needextend import (
-    Needextend,
-    extend_needs_data,
-    remove_needextend_node,
-)
+from sphinx_needs.directives.needextend import Needextend, extend_needs_data
 from sphinx_needs.functions import (
     find_and_replace_node_content,
     resolve_dynamic_values,
@@ -32,7 +28,7 @@
 from sphinx_needs.logging import get_logger
 from sphinx_needs.need_constraints import process_constraints
 from sphinx_needs.nodes import Need
-from sphinx_needs.utils import add_doc, profile
+from sphinx_needs.utils import add_doc, profile, remove_node_from_tree
 
 logger = get_logger(__name__)
 
@@ -407,7 +403,7 @@ def process_need_nodes(app: Sphinx, doctree: nodes.document, fromdocname: str) -
     post_process_needs_data(app)
 
     for extend_node in doctree.findall(Needextend):
-        remove_needextend_node(extend_node)
+        remove_node_from_tree(extend_node)
 
     format_need_nodes(app, doctree, fromdocname, list(doctree.findall(Need)))
 

sphinx_needs/directives/needbar.py

@@ -10,7 +10,7 @@
 from sphinx_needs.config import NeedsSphinxConfig
 from sphinx_needs.data import SphinxNeedsData
 from sphinx_needs.filter_common import FilterBase, filter_needs, prepare_need_list
-from sphinx_needs.utils import add_doc, save_matplotlib_figure
+from sphinx_needs.utils import add_doc, remove_node_from_tree, save_matplotlib_figure
 
 if not os.environ.get("DISPLAY"):
     matplotlib.use("Agg")
@@ -175,14 +175,7 @@ def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
     # for node in doctree.findall(Needbar):
     for node in found_nodes:
         if not needs_config.include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needextend.py

@@ -166,18 +166,3 @@ def extend_needs_data(
                             need[option] = [i.strip() for i in re.split(";|,", value)]
                     else:
                         need[option] = value
-
-
-def remove_needextend_node(node: Needextend) -> None:
-    """
-    Remove needextend from docutils node-tree, so that no output gets generated for it.
-    Ok, this is really dirty.
-    If we replace a node, docutils checks, if it will not lose any attributes.
-    But this is here the case, because we are using the attribute "ids" of a node.
-    However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-    before docutils claims about it.
-    """
-
-    for att in ("ids", "names", "classes", "dupnames"):
-        node[att] = []
-    node.replace_self([])

sphinx_needs/directives/needextract.py

@@ -19,7 +19,7 @@
 )
 from sphinx_needs.filter_common import FilterBase, process_filters
 from sphinx_needs.layout import create_need
-from sphinx_needs.utils import add_doc
+from sphinx_needs.utils import add_doc, remove_node_from_tree
 
 
 class Needextract(nodes.General, nodes.Element):
@@ -79,14 +79,7 @@ def process_needextract(
 
     for node in found_nodes:
         if not needs_config.include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needfilter.py

@@ -12,7 +12,7 @@
 from sphinx_needs.data import SphinxNeedsData
 from sphinx_needs.diagrams_common import create_legend
 from sphinx_needs.filter_common import FilterBase, process_filters
-from sphinx_needs.utils import add_doc, row_col_maker
+from sphinx_needs.utils import add_doc, remove_node_from_tree, row_col_maker
 
 
 class Needfilter(nodes.General, nodes.Element):
@@ -82,14 +82,7 @@ def process_needfilters(
     # for node in doctree.findall(Needfilter):
     for node in found_nodes:
         if not needs_config.include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needflow.py

@@ -21,7 +21,12 @@
 from sphinx_needs.diagrams_common import calculate_link, create_legend
 from sphinx_needs.filter_common import FilterBase, filter_single_need, process_filters
 from sphinx_needs.logging import get_logger
-from sphinx_needs.utils import add_doc, get_scale, split_link_types
+from sphinx_needs.utils import (
+    add_doc,
+    get_scale,
+    remove_node_from_tree,
+    split_link_types,
+)
 
 logger = get_logger(__name__)
 
@@ -286,14 +291,7 @@ def process_needflow(app: Sphinx, doctree: nodes.document, fromdocname: str, fou
     # for node in doctree.findall(Needflow):
     for node in found_nodes:
         if not needs_config.include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needgantt.py

@@ -23,7 +23,7 @@
 from sphinx_needs.directives.utils import SphinxNeedsLinkTypeException
 from sphinx_needs.filter_common import FilterBase, filter_single_need, process_filters
 from sphinx_needs.logging import get_logger
-from sphinx_needs.utils import MONTH_NAMES, add_doc
+from sphinx_needs.utils import MONTH_NAMES, add_doc, remove_node_from_tree
 
 logger = get_logger(__name__)
 
@@ -145,14 +145,7 @@ def process_needgantt(app: Sphinx, doctree: nodes.document, fromdocname: str, fo
     # for node in doctree.findall(Needgantt):
     for node in found_nodes:
         if not needs_config.include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needlist.py

@@ -15,7 +15,11 @@
     used_filter_paragraph,
 )
 from sphinx_needs.filter_common import FilterBase, process_filters
-from sphinx_needs.utils import add_doc, check_and_calc_base_url_rel_path
+from sphinx_needs.utils import (
+    add_doc,
+    check_and_calc_base_url_rel_path,
+    remove_node_from_tree,
+)
 
 
 class Needlist(nodes.General, nodes.Element):
@@ -70,14 +74,7 @@ def process_needlist(app: Sphinx, doctree: nodes.document, fromdocname: str, fou
     # for node in doctree.findall(Needlist):
     for node in found_nodes:
         if not include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needpie.py

@@ -22,6 +22,7 @@
 from sphinx_needs.utils import (
     add_doc,
     check_and_get_external_filter_func,
+    remove_node_from_tree,
     save_matplotlib_figure,
 )
 
@@ -118,14 +119,7 @@ def process_needpie(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
     # for node in doctree.findall(Needpie):
     for node in found_nodes:
         if not include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needsequence.py

@@ -21,7 +21,7 @@
 )
 from sphinx_needs.filter_common import FilterBase
 from sphinx_needs.logging import get_logger
-from sphinx_needs.utils import add_doc
+from sphinx_needs.utils import add_doc, remove_node_from_tree
 
 logger = get_logger(__name__)
 
@@ -89,14 +89,7 @@ def process_needsequence(
     # for node in doctree.findall(Needsequence):
     for node in found_nodes:
         if not include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/directives/needtable.py

@@ -17,7 +17,7 @@
 )
 from sphinx_needs.filter_common import FilterBase, process_filters
 from sphinx_needs.functions.functions import check_and_get_content
-from sphinx_needs.utils import add_doc, profile, row_col_maker
+from sphinx_needs.utils import add_doc, profile, remove_node_from_tree, row_col_maker
 
 
 class Needtable(nodes.General, nodes.Element):
@@ -141,15 +141,7 @@ def process_needtables(
     # for node in doctree.findall(Needtable):
     for node in found_nodes:
         if not needs_config.include_needs:
-            # Ok, this is really dirty.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # If we replace a node, docutils checks, if it will not lose any attributes.
-            # But this is here the case, because we are using the attribute "ids" of a node.
-            # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
-            # before docutils claims about it.
-            for att in ("ids", "names", "classes", "dupnames"):
-                node[att] = []
-            node.replace_self([])
+            remove_node_from_tree(node)
             continue
 
         id = node.attributes["ids"][0]

sphinx_needs/utils.py

@@ -653,3 +653,15 @@ def get_scale(options: Dict[str, Any], location: Any) -> str:
         )
         return "100"
     return scale
+
+
+def remove_node_from_tree(node: nodes.Element) -> None:
+    """Remove a docutils node in-place from its node-tree."""
+    # Ok, this is really dirty.
+    # If we replace a node, docutils checks, if it will not lose any attributes.
+    # But this is here the case, because we are using the attribute "ids" of a node.
+    # However, I do not understand, why losing an attribute is such a big deal, so we delete everything
+    # before docutils claims about it.
+    for att in ("ids", "names", "classes", "dupnames"):
+        node[att] = []
+    node.replace_self([])