functions: Fix broken parent-child node relationships

The find_and_replace_node_content function breaks parent-child node
relationships since it does not go through the docutils tools for
assigning node children. Utilize one of the built-in docutils methods [1]
for this since it correctly assigns the parent-child relationship of
each node.

Notably, the sphinxcontrib-spelling [2] extension is broken by this
broken parent-child relationship since if something is misspelled it
tries to identify which source line was impacted. When a node is added
as a child, setup_child(...) [3] code fixes up the source/line location
with the parent's information if needed.

A test has been added at the top-level which covers every single test
run by adding a build hook into the "doctree-resolved" hook. This test
is fairly simple - check each node (outside of the top node) and
validate that it has a parent assigned.

[1] https://github.com/docutils/docutils/blob/4e912fe000b1b6dc1466c0ad1c3d1787d40fd96d/docutils/docutils/nodes.py#L788-L794
[2] https://pypi.org/project/sphinxcontrib-spelling/
[3] https://github.com/docutils/docutils/blob/4e912fe000b1b6dc1466c0ad1c3d1787d40fd96d/docutils/docutils/nodes.py#L150-L157

Author: tim-nordell-nimbelink

sphinx_needs/functions/functions.py

@@ -256,7 +256,8 @@ def find_and_replace_node_content(
             for child in node.children:
                 new_child = find_and_replace_node_content(child, env, need)
                 new_children.append(new_child)
-                node.children = new_children
+                node.clear()
+                node.extend(new_children)
         else:
             node = nodes.Text(new_text)
         return node
@@ -268,7 +269,8 @@ def find_and_replace_node_content(
                 continue
             new_child = find_and_replace_node_content(child, env, need)
             new_children.append(new_child)
-        node.children = new_children
+        node.clear()
+        node.extend(new_children)
     return node
 
 

tests/conftest.py

@@ -254,6 +254,13 @@ def sphinx_test_tempdir(request) -> path:
     return sphinx_test_tempdir
 
 
+def test_check_parent_child(app: Sphinx, doctree: document, docname: str):
+    for idx, node in enumerate(doctree.findall()):
+        if idx == 0:
+            continue
+        assert node.parent
+
+
 @pytest.fixture(scope="function")
 def test_app(make_app, sphinx_test_tempdir, request):
     """
@@ -330,6 +337,8 @@ def test_app(make_app, sphinx_test_tempdir, request):
     # ``test_js`` behaves like a method.
     app.test_js = test_js.__get__(app, Sphinx)
 
+    app.connect("doctree-resolved", test_check_parent_child)
+
     yield app
 
     app.cleanup()