Skip to content

🐛 Fix spurious 'Unknown option' warning for needs_string_links fields#1722

Open
cpolzer wants to merge 3 commits into
useblocks:masterfrom
cpolzer:fix/string-links-unknown-option-warning
Open

🐛 Fix spurious 'Unknown option' warning for needs_string_links fields#1722
cpolzer wants to merge 3 commits into
useblocks:masterfrom
cpolzer:fix/string-links-unknown-option-warning

Conversation

@cpolzer

@cpolzer cpolzer commented Jun 12, 2026

Copy link
Copy Markdown

Problem

Fields declared via needs_string_links options (e.g. 'options': ['github']) that are not also registered in needs_fields / needs_extra_options trigger a spurious needs.directive warning:

WARNING: Unknown option 'github' [needs.directive]

and the need is silently dropped from the build output.

Root cause

create_schema() in sphinx_needs/needs.py only populates the schema's extra field registry from needs_fields and needs_extra_options. The options names inside needs_string_links entries are never registered.

Both NeedDirective.run() and create_need() validate option keys against schema.iter_extra_field_names() — any key absent from the registry hits the rejection path.

Fix

After building the extra field schema from needs_fields, iterate needs_config.string_links and register any options field names not yet in the schema as nullable string extra fields. This is the correct layer — the schema is the single source of truth consulted by both the directive parser and create_need().

Fields already registered via needs_fields are skipped, so there is no conflict when a project declares the field in both places.

Tests

New file tests/test_string_links.py with three regression tests:

  1. No warning — a field only in string_links options must not emit Unknown option
  2. Value stored — the field value appears in needs.json (verified via the needs builder)
  3. Guard — a truly unknown field (neither in needs_fields nor string_links) still warns

All existing test_needtable tests (which use needs_string_links with fields also in needs_fields) continue to pass.

Checklist

  • Tests added
  • tox -e ruff-check passes
  • tox -e mypy passes
  • Changelog updated (docs/changelog.rst, Unreleased > Bug fixes)

Fields declared via needs_string_links 'options' that are not also
registered in needs_fields were rejected by create_need (and flagged by
NeedDirective.run) as unknown, emitting a needs.directive warning and
silently dropping the need.

Fix: in create_schema(), after building the extra field schema from
needs_fields, iterate needs_config.string_links and register any
'options' field names not yet in the schema as nullable string extra
fields.  This is the single source of truth consulted by both
NeedDirective.run() and create_need(), so no other changes are needed.

Adds tests/test_string_links.py with three regression tests:
- no spurious warning when option is only in string_links
- field value is stored in needs.json (verified via needs builder)
- truly unknown fields still warn (guard test)
@cpolzer cpolzer closed this Jun 25, 2026
@cpolzer cpolzer force-pushed the fix/string-links-unknown-option-warning branch from ba5a475 to ddef10e Compare June 25, 2026 15:23
@cpolzer cpolzer reopened this Jun 25, 2026
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.

1 participant