fix: improve generic Mermaid and Need template rendering - #832
AlexanderLanin merged 5 commits into
Conversation
|
Documentation preview for this pull request is available at: |
|
|
||
| # Relative paths of all rst files in RST_DIR | ||
| RST_FILES = [str(f.relative_to(RST_DIR)) for f in Path(RST_DIR).rglob("*.rst")] | ||
| _NEED_DIRECTIVE_PATTERN = re.compile(r"^\s*\.\.\s+([A-Za-z][\w-]*)::") |
There was a problem hiding this comment.
No way this does only what it should.
But I don't think it matters here, as this is just a display helper, and if the regex is wrong it wont break something important.
There was a problem hiding this comment.
this is our tests. so it can only break if we change the test-rst files to something incompatible.
And since this matches too much as you mentioned, there is a check for match.group(1) in need_directive_names
| if source is not None: | ||
| # Prefer Sphinx-Needs' backlink index when the source Need is | ||
| # present. Keep these results first, but do not assume that a | ||
| # non-empty index is complete: links injected later in the build | ||
| # may only be visible on the outgoing Need fields. | ||
| for link in source.get_backlinks(link_type, as_str=False): | ||
| target = _find_need(needs, link.to_link_string()) | ||
| if target is not None and target["id"] not in linked_ids: | ||
| linked.append(target) | ||
| linked_ids.add(target["id"]) | ||
|
|
||
| # During a post-template reread, Sphinx-Needs may not have rebuilt | ||
| # backlink caches yet. The current Need may also be temporarily absent | ||
| # from the live environment while its document is reread. Derive the | ||
| # reverse relation from outgoing links in all cases and merge it with | ||
| # the indexed results above. This catches new links while preserving | ||
| # the index order and avoids duplicate Needs. | ||
| source_id = _base_need_id(need_id) | ||
| for candidate in needs.values(): | ||
| points_to_source = any( | ||
| _base_need_id(link.to_link_string()) == source_id | ||
| for link in candidate.get_links(link_type, as_str=False) | ||
| ) | ||
| if points_to_source and candidate["id"] not in linked_ids: | ||
| linked.append(candidate) | ||
| linked_ids.add(candidate["id"]) | ||
| return linked |
There was a problem hiding this comment.
I wonder if you can get around this double checking if you wait for the needs_locked event?
Cause as far as I know, then the needs are actually locked and everything is evaluated (so the need should be fully complete)
There was a problem hiding this comment.
I looked into the event timing. In our Sphinx-Needs version the event is called needs-before-sealing (there is no needs_locked event). It runs after link/backlink resolution, just before the Need data is locked.
That is useful for inspecting finalized links, but this extension needs to reread report documents, which removes and recreates the page’s Needs. Doing that after link resolution would add the rebuilt Needs too late for that resolution pass (and is outside the intended read phase for adding/removing Needs).
So the current env-updated reread is intentional: it runs after the merged Needs and injected testcase links are available, while the collection is still in its read/mutable phase. Since backlinks are not finalized yet at that point, the helper derives reverse links from outgoing links as a fallback.
| finally: | ||
| # The exception, if any, must still propagate. Clear the process-local | ||
| # snapshot first so stale Needs cannot affect later rereads or builds | ||
| # that continue in the same Python process. | ||
| _temporarily_removed_needs = {} |
There was a problem hiding this comment.
Finally will always run no?
so this happens always, not just in an exception like the comment states.
There was a problem hiding this comment.
yeah... to be fair the comment says "if any". I can improve wording!
MaximilianSoerenPollak
left a comment
MaximilianSoerenPollak
left a comment
There was a problem hiding this comment.
Some questions
MaximilianSoerenPollak
left a comment
MaximilianSoerenPollak
left a comment
There was a problem hiding this comment.
Questions answered. Looks good to me now.
Why
This PR makes the reusable documentation rendering path reliable for generated metamodel diagrams and graph-driven Sphinx-Needs templates. Without these fixes, hyphenated type names can produce invalid or ambiguous Mermaid references, nested Needs can be missed by the file-based checks, and post-template rereads can lose the Needs needed to resolve links and backlinks.
What changed
This PR contains reusable rendering and test-infrastructure fixes; it does not introduce the tool-verification report metamodel content.