Repository navigation
Show preview of the linked need in a pop-up - #16
Merged
Merged
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Unsanitized fetched markup creates a security risk, alongside accessibility and unnecessary-fetch concerns.
1 open finding
What changed in this PR
Adds linked-need card previews to generated HTML documentation.
Changes:
- Adds preview behavior and styling.
- Registers and copies the JavaScript asset.
- Documents and tests asset integration.
| File | Description |
|---|---|
sphinx/_static/zdocs-needs.css |
Styles preview popups. |
sphinx/_static/zdocs-need-preview.js |
Fetches and displays linked cards. |
sphinx/_extensions/need_cards.py |
Registers and copies the script. |
sphinx/_extensions/_tests/test_need_cards.py |
Tests script integration. |
doc/manual/reference/directives-and-roles.rst |
Documents preview behavior. |
doc/api/python/extensions.rst |
Updates extension summary. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
When the pointer stays on a link in a need card, and the link goes to another need card, a popup shows a copy of that card: the head, then the fields, then the text. The script fetches the target page in the browser, once per page, so the link can go to another document too. need_cards adds zdocs-need-preview.js to each page; zdocs-needs.css styles the popup. Only a link that goes to a need gets a popup: need_cards gives it the class zd-need-ref, so a link to a Doxygen page does not fetch that page. The popup also opens on keyboard focus, and Escape or a scroll of the page closes it. A device without hover gets no popups. A page opened as file:// cannot fetch other pages, so there only the needs on the same page get a preview. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
tobiaskaestner
force-pushed
the
tkaestner/need-preview
branch
from
October 13, 2026 19:05
2dcf490 to
5c52d62
Compare
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
When the pointer stays on a link in a need card, and the link goes to another need card, a popup shows a copy of that card: the head, then the fields, then the text. The script fetches the target page in the browser, once per page, so the link can go to another document too. need_cards adds zdocs-need-preview.js to each page; zdocs-needs.css styles the popup.
The popup also opens on keyboard focus, and Escape or a scroll of the page closes it. A device without hover gets no popups. A page opened as file:// cannot fetch other pages, so there only the needs on the same page get a preview.
Only a link that goes to a need gets a popup: need_cards gives it the class
zd-need-ref, so a link to a Doxygen page (Source, See also) does not make the script fetch that page.