8.3.0

What's Changed

✨ needs_role_need_template is now rendered with Jinja

needs_role_need_template — and the inline [[...]] form of the :need: role — are now rendered with Jinja instead of Python's str.format (#1738, closes #1697).

This brings Jinja's filters and control structures to need references — for example {% if is_need %}…{% endif %} or {{ type | upper }} — and adds the variables id_complete, id_parent, id_part, is_need and is_part, available directly or through a need object (e.g. {{ need.type }}).

Backward compatible: existing setups are unaffected on upgrade — a template still written in the old str.format style is detected and rendered the old way, emitting a single needs.deprecated warning that points at the migration ({field} → {{ field }}). The old syntax is deprecated and will be removed in a future release.

Thanks to @PhilipPartsch for the initial proposal (#1698)!

Full Changelog: 8.2.0...8.3.0

8.2.0

This release is all about building one documentation source for many product variants. If you maintain docs that differ by architecture, build flavour, feature flags or customer edition, the new variant-data tooling lets you describe those parameters once and let Sphinx-Needs do the branching — in filters, in need fields, in prose, and in whole sections. The other headline is network_back schema validation, which finally lets you express link-coverage rules from the side of the relationship where they actually make sense.

Full Changelog: v8.1.1...v8.2.0

✨ Variant data: describe your build once, reuse it everywhere

The centrepiece of 8.2.0 is needs_variant_data — a structured, namespaced replacement for the old flat needs_filter_data. You define your variant parameters as ordinary (nestable) data and read them back through a clean var namespace:

# conf.py
needs_variant_data = {
    "cpu": "arm",
    "debug": True,
    "build": {"optimization": 2, "features": ["feature_a", "feature_b"]},
}

Once configured, the same var data is available in four complementary ways, so you can pick the right tool for each spot in your docs:

• In filters — var.build.debug reads far more naturally than the old bracket syntax, and nested data avoids clashing with your need field names:

  .. needtable::
     :filter: var.cpu == "arm" and var.build.debug == True

• In need field values — inject a variant value straight into a field with the new <{ ... }> syntax (for any field flagged parse_variants):

  .. req:: Example
     :id: VD_001
     :arch: <{ var.cpu }>

• In prose — the new variant role drops a resolved value straight into your text, rendering the configured cpu value as arm.

• In whole blocks — the new if directive includes or excludes entire sections (needs and all) at parse time, based on a var expression:

  .. if:: var.cpu == "arm"
  
     This section — and every need inside it — is only built for ARM.

Variant data can also be loaded from JSON via needs_variant_data_file and swapped per build with sphinx-build -D needs_variant_data_file=..., making it easy to generate variant-specific outputs from a single source tree (#1715, #1716, #1721, #1737).

Improvements

• ✨ Add a network_back schema-validation key, the sibling of network, that validates a need's incoming links instead of its outgoing ones. This lets you state a rule from the target's point of view — for example "every requirement must be covered by at least one test" — once, on the requirement, instead of repeating it on every test. It reuses the familiar items / contains / minContains / maxContains structure and can be freely mixed and nested with network (see Incoming link validation) (#1731)
• 👌 Allow link fields in needservice directive options, so needs created via a custom service can declare links to other needs (#1632). Thanks to @filipepcampos
• 👌 Honor -D command-line overrides when loading needs from a TOML file, so per-build configuration works as expected (#1717)
• 👌 Include the JSON location (path) in $ref resolution error messages, making schema-configuration mistakes much easier to track down (#1736)
• 👌 Track JSON files imported via needimport as build dependencies, so editing an imported file triggers a rebuild (#1730). Thanks to @yhontyk
• 🔧 Add a root context7.json configuration file so AI assistants using Context7 can discover the live Sphinx-Needs documentation and use the project-specific reference instead of stale training data (#1719)

Deprecations

• ⚠️ Deprecate needs_filter_data in favour of the new, structured needs_variant_data. It keeps working for now but emits a warning; the flat data it provides is injected at the filter root and can collide with need field names, which the namespaced var data avoids (#1715)

Breaking changes

• ‼️ Remove the discontinued Open-Needs service (#1732)

  The Open-Needs project is discontinued and open-needs.org no longer resolves, so the open-needs service has been removed. The sphinx_needs.services.open_needs.OpenNeedsService import and the params, prefix and url_postfix extra fields that the service registered are no longer available.

Bug fixes

• 🐛 Fix needpie raising All wedge sizes are zero on matplotlib 3.11+ when a pie has no data (e.g. zero matching needs); an empty pie with its legend is now rendered instead (#1727)
• 🐛 Sort need link and backlink lists in needs.json and HTML output using natural, case-insensitive ordering (e.g. REQ_2 < REQ_9 < REQ_10) and collapse duplicate entries, so build outputs are reproducible regardless of need load order (e.g. when using needs_external_needs) (#1371)
• 🐛 Fix parent-child relationship of newly created nodes for needs. This fixes interoperability with Sphinx extensions that look up source lines, like sphinxcontrib-spelling (#1564). Thanks to @tim-nordell-nimbelink

8.1.1

What's Changed

• 🐛 Fix Docker build by switching PlantUML source to GitHub releases by @ubmarco in #1708
• ⚡️ Add NeedItem.is_in_document() by @chrisjsewell in #1709
• 🐛 Fix needs_schema_definitions triggering full rebuilds by @ubmarco in #1712
• 🚀 Release v8.1.1 by @ubmarco in #1713

Full Changelog: 8.1.0...8.1.1

8.1.0

This release focuses on filter performance improvements and bug fixes.

Full Changelog: 8.0.0...8.1.0

Performance

• ⚡️ Short-circuit simple filter expressions to avoid eval() overhead (#1677)

  Common filter patterns (e.g. id == "REQ_001", type == "spec") are now matched and evaluated directly without invoking Python's eval(), significantly reducing filtering time for large need sets.

• ⚡️ Add NeedItem.filter_context() to avoid costly {**need} unpacking (#1706)

  Filter evaluation no longer creates a full dictionary copy of each need on every filter call, reducing memory allocations and improving throughput.

• ⚡️ Cache NeedLink filter string (#1705)

  Pre-compute and store the filter string on NeedLink construction, avoiding repeated string formatting on every access through NeedItem.__getitem__.

Bug fixes

• 🐛 Fix needflow rendering very dark / black nodes when a need type has no color set in needs_types (#1664, #1702).
  Previously a hard-coded #000000 fallback was used as the fill color, which produced unreadable nodes — especially under browser dark mode. When no color is configured, no color is emitted and the diagram engine's default node color is used.

  Note: This is a minor behavior change for users with needs_types entries that omit the color key: diagrams (needflow, needuml, needgantt) that previously rendered such nodes as solid black will now render them with the diagram engine's default node color (typically light). To preserve the old appearance, set "color": "#000000" explicitly on the affected needs_types entry.

• 🐛 Fix :need: role in section headings by registering NeedRef node with Sphinx's LaTeX builder (#1700).

8.0.0

See https://sphinx-needs.readthedocs.io/en/stable/changelog.html

What's Changed

• 📚 Fix 7.0.0 release date by @ubmarco in #1666
• 🐛 Fix linkcheck CI job warnings by @Copilot in #1667
• 🧪 Add tests for variants in links by @ubmarco in #1669
• 📚 DOCS: add sphinx-ai-index to sphinx docs builder by @Felix-Ruh in #1671
• ♻️ Introduce NeedLink structured internal representation for links by @chrisjsewell in #1670
• 🔧 Use NeedLink directly in update_back_links function by @chrisjsewell in #1672
• ♻️ Store NeedLink instead of str in LinksLiteralValue and LinksFunctionArray by @chrisjsewell in #1673
• ♻️ Add _split_link_list parser with condition syntax support by @chrisjsewell in #1674
• ✨ Add conditional need link assessment by @Copilot in #1675
• 🔧 Use get_links(as_str=False) in needextend to avoid round-trip serialization by @chrisjsewell in #1678
• 🔧 Store NeedPartData.backlinks as NeedLink instead of str by @chrisjsewell in #1679
• 👌 Parse link conditions from imported and external needs by @chrisjsewell in #1680
• 👌 Add needs_json_include_link_conditions config option by @Copilot in #1681
• ♻️ Store NeedLink on NeedRef node at parse time instead of re-parsing later by @Copilot in #1682
• 🔧 Bump ENV_DATA_VERSION to 4 for NeedLink storage format change by @Copilot in #1683
• 👌 Add parse_conditions configuration for link types by @Copilot in #1684
• ♻️ Fix links_from_content to use parsed doctree nodes instead of regex by @chrisjsewell in #1685
• 🧪 Add some more tests for links_from_content by @chrisjsewell in #1686
• 🚀 Release v8.0.0 by @chrisjsewell in #1688

New Contributors

• @Felix-Ruh made their first contribution in #1671

Full Changelog: 7.0.0...8.0.0

7.0.0

See https://sphinx-needs.readthedocs.io/en/latest/changelog.html#release-7-0-0

What's Changed

• 🔧 Add validate_extra_option_schema by @chrisjsewell in #1602
• 🔧 Store full schema on FieldSchema by @chrisjsewell in #1603
• ♻️ Move needs_statuses and need_tags checking to schema validation by @chrisjsewell in #1605
• 🔧 Remove use of extra_options after config resolution by @chrisjsewell in #1607
• ✨ Add uniqueItems to array schema validation by @chrisjsewell in #1610
• ✨ Add needs_fields, deprecate need_extra_options, need_statuses, need_tags by @chrisjsewell in #1611
• ✨ Add default and predicates keys to needs_fields and needs_extra_links, deprecates needs_global_options by @chrisjsewell in #1612
• ✨ Add nullable key to needs_fields items by @chrisjsewell in #1613
• 🔧 Simplify import_prefix_link_edit by @chrisjsewell in #1615
• ✨🎄 Add parse_variants to needs_fields / needs_extra_link, deprecate needs_variant_options by @chrisjsewell in #1614
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #1600
• 🔧 Fix typo by @ubmarco in #1618
• 🔧 Move link schema to LinkSchema by @chrisjsewell in #1617
• 🔧 Add AGENTS.md by @chrisjsewell in #1621
• 🔧 Update Python version for Codecov by @ubmarco in #1625
• 📚 Fix typo in documentation for GitHub service example by @ahamez in #1634
• 👌 Minor improvements for needs.fields inheritance by @chrisjsewell in #1635
• 🧪 Add tests for create_inherited_field by @chrisjsewell in #1636
• 📚 Fix small grammatical error in need.rst by @ahamez in #1637
• ♻️ Migrate use of extra_links to Schema-Based Access by @chrisjsewell in #1638
• 🔧 Refactor populate_field_type to use type-directed schema walking by @chrisjsewell in #1639
• ♻️ Add add_field API; deprecate add_extra_option by @chrisjsewell in #1641
• 🔧 Rename "option" to "field" by @chrisjsewell in #1642
• 👌 Allow add_field API to set defaults/predicates by @chrisjsewell in #1643
• ‼️ Make need fields added by services nullable and default to null by @chrisjsewell in #1644
• ‼️ Make needs_fields and add_field default to nullable and no default by @chrisjsewell in #1645
• 👌 Default values of extra fields now checked against schema definitions by @chrisjsewell in #1647
• 🐛 Fix schema validation returning per need errors by @PhilipPartsch in #1640
• 📚 Fix typo in sort of needtable documentation by @PhilipPartsch in #1619
• 🔧 Simplify generate_needs function by @chrisjsewell in #1651
• ⚠️ Separate reduced vs full need representation for schema validation by @chrisjsewell in #1652
• 🔧 simplify field/link validation by @chrisjsewell in #1654
• 🔧 Refactor schema validation: separate select filtering from local validation by @chrisjsewell in #1655
• ⬆️ Support Sphinx 9 and Docutils 0.22 by @mitya57 in #1653
• ⚠️ Migrate needs_extra_links to needs_links by @chrisjsewell in #1649
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #1623
• 🐛 Fix needextend data purging and deterministic ordering by @chrisjsewell in #1657
• 🔧 Add GitHub Copilot setup workflow for dev environment configuration by @Copilot in #1628
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #1656
• 👌 Expose parse_dynamic_functions in field/link configuration by @chrisjsewell in #1660
• ♻️ Replace jinja2 with minijinja for template rendering by @Copilot in #1659
• 🐛 Fix needs.json read/write when no needs are present by @qznc in #1661
• 🚀 Release v7.0.0 by @chrisjsewell in #1662

New Contributors

• @ahamez made their first contribution in #1634
• @mitya57 made their first contribution in #1653
• @Copilot made their first contribution in #1628
• @qznc made their first contribution in #1661

Full Changelog: 6.3.0...7.0.0

v6.3.0

What's Changed

• 👌 Relative paths from toml configuration by @chrisjsewell in #1589
• 👌 Ensure extra_links schema contains item type by @chrisjsewell in #1595
• 👌 Validate all schemas compile during config resolution by @chrisjsewell in #1596
• ♻️ Remove typeguard dependency by @chrisjsewell in #1597
• ⬆️ Support Python 3.14 by @chrisjsewell in #1598
• 📚 Fix typo in tutorial documentation by @dskkato in #1591
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #1586

New Contributors

• @dskkato made their first contribution in #1591

Full Changelog: 6.2.0...6.3.0

6.2.0

What's Changed

• 🧪 Fix schema benchmark tests by @ubmarco in #1577
• 🧪 Improve schema process benchmarking by @chrisjsewell in #1579
• 🔧 Reduce nested functions in get_ontology_warnings by @chrisjsewell in #1578
• 👌 Improve schema validation performance (pre-compute validators) by @chrisjsewell in #1581
• 👌 Improve schema validation performance (use jsonschema-rs) by @chrisjsewell in #1582
• 👌 Improve schema validation performance (improve reduce_needs) by @chrisjsewell in #1583
• 👌 Improve schema validation performance (cache recursive validators) by @chrisjsewell in #1584
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #1421
• 🚀 Release v6.2.0 by @chrisjsewell in #1585

Full Changelog: 6.1.1...6.2.0

v6.1.1

What's Changed

• 👌 Allow . in schema regex by @ubmarco in #1568
• 🐛 Fix schema network type injection by @ubmarco in #1570
• 🐛 needs.json for nullable fields by @ubmarco in #1571
• 🔧 Remove mutable global variables by @chrisjsewell in #1575
• ✨ Add needs_schema_validation_enabled configuration by @chrisjsewell in #1574
• ✨ Add allow_type_coercion configuration for external/import needs.json reads by @chrisjsewell in #1573

Full Changelog: 6.1.0...6.1.1

v6.1.0

What's Changed

• 🐛 Fix schema rule severity by @ubmarco in #1535
• 📚 Co-locate dynamic and variant function docs by @chrisjsewell in #1544
• 🧪 Add snapshot test for field schema by @chrisjsewell in #1545
• 🔧 Derive core FieldSchema from NeedsCoreFields by @chrisjsewell in #1546
• 👌 Make incoming/outgoing keys optional in needs_extra_links by @chrisjsewell in #1548
• 🔧 Removed unused code by @chrisjsewell in #1550
• 📚 Enable link to full schema example by @ubmarco in #1538
• 🔧 Variable typo by @ubmarco in #1555
• 📚 Improve schema docs by @ubmarco in #1554
• 📚 Fix linkchecks by @ubmarco in #1556
• 🔧 Run new ubc action on docs by @ubmarco in #1541
• 👌 Improve schema severity handling by @ubmarco in #1561
• ♻️ Early resolution of schema_debug_path by @ubmarco in #1563
• 🚀 Release v6.1.0 by @ubmarco in #1565

Full Changelog: 6.0.1...6.1.0