👌 Add parse_conditions configuration for link types

[Copilot]

Adds a parse_conditions option to link types, allowing users to disable [condition] bracket parsing per link type. Follows the existing pattern of parse_dynamic_functions and parse_variants. Defaults to True for backward compatibility.

Changes

• need_item.py: Add parse_conditions: bool = True kwarg to NeedLink.from_string and from_string_with_warnings; when False, skip bracket parsing and pass the raw string to parse_address
• config.py: Add parse_conditions: NotRequired[bool] to NeedLinksConfig
• needs_schema.py: Add field to LinkSchema with validation; thread it through convert_directive_option, convert_or_type_check, and _split_link_list
• needs.py: Read parse_conditions from link config in create_schema()
• docs/configuration.rst: Document the option in both needs_links and needs_schema_definitions sections
• Unit tests: Cover parse_conditions=False in NeedLink.from_string and _split_link_list
• End-to-end test: Add a raw_links link type with parse_conditions: False to tests/doc_test/doc_link_conditions, with a dedicated test_parse_conditions_disabled test verifying brackets are treated as literal ID text in a full Sphinx build

Usage

needs_links = [
    {
        "option": "blocks",
        "incoming": "is blocked by",
        "outgoing": "blocks",
        "parse_conditions": False,  # brackets treated as literal ID text
    },
]

# With parse_conditions=False
NeedLink.from_string("NEED-1[cond]", parse_conditions=False)
# => NeedLink(id="NEED-1[cond]", condition=None)

Original prompt

👌 Add parse_conditions configuration for link types

Summary

Add a parse_conditions kwarg to NeedLink.from_string (and from_string_with_warnings) that controls whether the [condition] bracket syntax is parsed. Expose this as a configuration option on link types (analogous to the existing parse_dynamic_functions and parse_variants options). Default to True to preserve backward compatibility.

Motivation

Currently, NeedLink.from_string always attempts to parse [condition] brackets. There is no way to disable condition parsing for a specific link type. The existing parse_dynamic_functions and parse_variants configurations on link types demonstrate the pattern — parse_conditions follows the same approach for conditions.

Changes Required

1. sphinx_needs/need_item.py — NeedLink.from_string and NeedLink.from_string_with_warnings

• Add a parse_conditions: bool = True parameter to both from_string and from_string_with_warnings.
• When parse_conditions=False, skip all bracket parsing and pass the entire string directly to parse_address (treating it as a plain ID or ID.part).
• from_string must pass the kwarg through to from_string_with_warnings.

2. sphinx_needs/config.py — NeedLinksConfig

• Add parse_conditions: NotRequired[bool] to the NeedLinksConfig TypedDict, with a docstring: """Whether conditions (bracket syntax) are parsed in this field."""

3. sphinx_needs/needs_schema.py — LinkSchema

• Add parse_conditions: bool = True field to the LinkSchema dataclass.
• Add validation in __post_init__: if not isinstance(self.parse_conditions, bool): raise ValueError("parse_conditions must be a boolean.")
• In convert_directive_option(): pass self.parse_conditions to _split_link_list().
• In convert_or_type_check(): when calling NeedLink.from_string(item) or NeedLink.from_string(v) in the else branches, pass parse_conditions=self.parse_conditions.

4. sphinx_needs/needs_schema.py — _split_link_list()

• Add a parse_conditions: bool = True parameter.
• Pass it through to NeedLink.from_string_with_warnings() when parsing plain link items in the _flush_current inner function.

5. sphinx_needs/needs.py — create_schema() (around line 1028)

• Read parse_conditions from the link config dict and pass it to the LinkSchema constructor: parse_conditions=link.get("parse_conditions", True).

6. docs/configuration.rst — Link type documentation

• Add documentation for the parse_conditions option in the needs_links section, following the pattern of parse_variants and parse_dynamic_functions:

  - ``parse_conditions``: If set to ``False``, the ``[condition]`` bracket syntax will not be parsed for this link type.
      Default: ``True``.
  

7. Tests

• tests/test_need_item_api.py — In TestNeedLinkFromString, add tests for parse_conditions=False:

  • NeedLink.from_string("NEED-1[cond]", parse_conditions=False) should return NeedLink(id="NEED-1[cond]", condition=None) (brackets treated as literal ID text).
  • NeedLink.from_string("NEED-1.partA[cond]", parse_conditions=False) should return NeedLink(id="NEED-1", part="partA[cond]", condition=None).
  • NeedLink.from_string("NEED-1", parse_conditions=False) should return NeedLink(id="NEED-1") (no change for plain IDs).
  • Also test from_string_with_warnings with parse_conditions=False returns empty warnings list.

• tests/test_needs_schema.py — In test_split_link_list, add parameterized cases where parse_conditions=False is passed to _split_link_list (this will require updating the test's parameter signature to include the new arg).

Files touched

1. sphinx_needs/need_item.py
2. sphinx_needs/config.py
3. sphinx_needs/needs_schema.py
4. sphinx_needs/needs.py
5. docs/configuration.rst
6. tests/test_need_item_api.py
7. tests/test_needs_schema.py

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[chrisjsewell]

@copilot add to tests/doc_test/doc_link_conditions to test this new config in an end to end way

[Copilot]

@copilot add to tests/doc_test/doc_link_conditions to test this new config in an end to end way

Added in 5bfa2fe. The e2e test adds a raw_links link type with parse_conditions: False to the doc_link_conditions conf.py, adds a need (SPEC_RAW_001) that uses bracket syntax in that link, and verifies that brackets are treated as literal ID text (producing a dead link warning instead of a condition). Also added a dedicated test_parse_conditions_disabled test function that checks the JSON output confirms no condition was extracted.

[chrisjsewell]

@copilot fix FAILED tests/test_basic_doc.py::test_build_needs[test_app0] - AssertionError: assert [+ received] == [- snapshot]

[Copilot]

@copilot fix FAILED tests/test_basic_doc.py::test_build_needs[test_app0] - AssertionError: assert [+ received] == [- snapshot]

Fixed in 4c19a50. The test_basic_doc snapshot needed updating to include the new parse_conditions=True field in the LinkSchema repr for both links and parent_needs.

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.04%. Comparing base (4e10030) to head (4c19a50).
⚠️ Report is 272 commits behind head on master.

Files with missing lines	Patch %	Lines
sphinx_needs/needs_schema.py	71.42%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1684      +/-   ##
==========================================
+ Coverage   86.87%   89.04%   +2.16%     
==========================================
  Files          56       71      +15     
  Lines        6532    10178    +3646     
==========================================
+ Hits         5675     9063    +3388     
- Misses        857     1115     +258     

Flag	Coverage Δ
pytests	89.04% <85.71%> (+2.16%)	⬆️

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.