Skip to content

🐛 Fix need role in section headings by registering NeedRef node#1700

Open
Copilot wants to merge 1 commit intomasterfrom
copilot/add-html-build-test-restructuredtext-heading
Open

🐛 Fix need role in section headings by registering NeedRef node#1700
Copilot wants to merge 1 commit intomasterfrom
copilot/add-html-build-test-restructuredtext-heading

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 7, 2026

Using :need: in an RST section heading crashes the build because SphinxContentsFilter (used by TocTreeCollector for TOC generation) doesn't know how to visit NeedRef nodes.

.. req:: My Requirement
   :id: REQ_001

Section with need ref :need:`REQ_001`
-------------------------------------

Fails with: SphinxContentsFilter visiting unknown node type: NeedRef

Fix: Register NeedRef with app.add_node() using dummy visitors, same pattern as NeedPart:

app.add_node(
    NeedRef,
    html=(visitor_dummy, visitor_dummy),
    latex=(visitor_dummy, visitor_dummy),
)
  • sphinx_needs/needs.py — add node registration for NeedRef
  • tests/test_role_need_in_heading.py — new test asserting the heading renders with a resolved need reference
  • tests/doc_test/doc_role_need_in_heading/ — minimal test project

…ration

The NeedRef node was not registered with app.add_node(), causing
SphinxContentsFilter to fail when encountering it in section headings
(used for TOC generation). Fixed by registering NeedRef with dummy
visitor methods.

Agent-Logs-Url: https://github.com/useblocks/sphinx-needs/sessions/383d8ee1-76c6-41b3-b820-931501775be8

Co-authored-by: chrisjsewell <2997570+chrisjsewell@users.noreply.github.com>
@chrisjsewell chrisjsewell changed the title Fix need role in section headings by registering NeedRef node 🐛 Fix need role in section headings by registering NeedRef node May 7, 2026
@chrisjsewell chrisjsewell marked this pull request as ready for review May 7, 2026 10:06
@chrisjsewell chrisjsewell requested a review from ubmarco May 7, 2026 10:06
@codecov
Copy link
Copy Markdown

codecov Bot commented May 7, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.30%. Comparing base (4e10030) to head (0c96117).
⚠️ Report is 277 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #1700      +/-   ##
==========================================
+ Coverage   86.87%   89.30%   +2.42%     
==========================================
  Files          56       72      +16     
  Lines        6532    10325    +3793     
==========================================
+ Hits         5675     9221    +3546     
- Misses        857     1104     +247     
Flag Coverage Δ
pytests 89.30% <100.00%> (+2.42%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants