🐛 `:need_outgoing:` / `:need_incoming:` naming a need that does not exist raises a KeyError and stops the build

Open Beginner friendly
  • Is something wrong?
#2,413 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Start by reading roles/need_ref.py, where the existence check (if need_id_main not in all_needs) and the "linked need … not found" warning already live. Then compare process_need_incoming in roles/need_incoming.py and process_need_outgoing in roles/need_outgoing.py, which index the view directly at all_needs[node["reftarget"]]. Add the same guard so a missing target emits a warning and the page still renders, and cover it with a test that builds a document referencing a nonexistent need id.

Written by the indexing model from the issue text.

Description

bug pkg: sphinx-needs

A :need_outgoing: or :need_incoming: role whose target id names no need (for example a need that was deleted)
raises KeyError in doctree-resolved, which ends the build, on a fresh build:
process_need_incoming (roles/need_incoming.py) and process_need_outgoing (roles/need_outgoing.py) index the needs view
with the role's target (all_needs[node["reftarget"]]) without checking it exists, and the view raises (views.py:164).
:need: checks first (roles/need_ref.py: if need_id_main not in all_needs) and warns "linked need … not found".

In an incremental build on master the page holding the role is not re-written, so the build stays green with a stale page;
the incremental-build pull request (precise dependency rules) re-writes that page, which then fails the same way a fresh build does.

Expected: a warning naming the missing id, as :need: gives, and the rest of the page rendered.

Related: #1437 (how these roles use Sphinx's reference machinery).

Found while reviewing the incremental-build branch (claude/vibrant-allen-o22lej-incremental), on master 8bd37988.

Dominant language
Python
Stars
309
Forks
103
Avg merge
3h 37m
Merged PRs (30d)
170

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from useblocks/sphinx-needs

All issues in useblocks/sphinx-needs

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.