functions: Fix broken parent-child node relationships #1564
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tim-nordell-nimbelink
force-pushed
the
fix/node_parent_child
branch
from
3c26d3d to
e73e606
Compare
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. The Element class in docutils will [1] iterate over each added child; we'll mimic that here. (We can't use the Element variant since we're only guaranteed to be of type Node, which doesn't have these helper functions, unfortunately.) 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
tim-nordell-nimbelink
force-pushed
the
fix/node_parent_child
branch
from
e73e606 to
9b14297
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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