🐛 functions: Fix broken parent-child node relationships (#1564)

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

docs/changelog.rst

@@ -56,6 +56,10 @@ Bug fixes
   of need load order (e.g. when using :ref:`needs_external_needs`)
   (:issue:`1371`)
 
+- 🐛 Fix parent-child relationship of newly created nodes for needs. This
+  fixes interoperability with Sphinx extensions that look up source lines,
+  like sphinxcontrib-spelling (:issue:`1564`)
+
 .. _`release:8.1.1`:
 
 8.1.1

sphinx_needs/functions/functions.py

@@ -263,7 +263,10 @@ 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.children = new_children
+            for subchild in node.children:
+                node.setup_child(subchild)
         else:
             node = nodes.Text(new_text)
         return node
@@ -275,7 +278,10 @@ 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
+        for subchild in node.children:
+            node.setup_child(subchild)
     return node
 
 

tests/conftest.py

@@ -255,6 +255,13 @@ def sphinx_test_tempdir(request) -> Path:
     return sphinx_test_tempdir
 
 
+def _check_parent_child(app: Sphinx, doctree: document, docname: str):
+    for idx, node in enumerate(doctree.findall()):
+        if idx == 0:
+            continue
+        assert node.parent is not None
+
+
 @pytest.fixture(scope="function")
 def test_app(make_app, sphinx_test_tempdir, request):
     """
@@ -333,6 +340,12 @@ def test_app(make_app, sphinx_test_tempdir, request):
     # ``test_js`` behaves like a method.
     app.test_js = test_js.__get__(app, Sphinx)
 
+    # Check created all parent-child node relationships after any other
+    # code within the doctree-resolved event by setting the priority to 999.
+    # Placing this test here provides coverage for quite a few tests in
+    # the suite, and hopefully will test any future features.
+    app.connect("doctree-resolved", _check_parent_child, priority=999)
+
     yield app
 
     app.cleanup()