Deprecated needs options¶

This page documents [needs] configuration options that were deprecated in sphinx-needs 7.0. They remain supported for backward compatibility with sphinx-needs < 7 but should be replaced with their recommended alternatives in new projects.

Global options¶

Deprecated since version 0.25.0: The [needs.global_options] section (needs_global_options in sphinx-needs) was deprecated in sphinx-needs 7.0. Default values and conditional predicates should instead be set directly on each field or link via their default and predicates keys in [needs.fields] or [needs.links] (see Fields and Link types).

For example, instead of:

[needs.global_options.status]
default = "draft"
predicates = [['status == "open"', "active"]]

Prefer:

[needs.fields.status]
default = "draft"
predicates = [['status == "open"', "active"]]

The [needs.global_options] format remains supported for backward compatibility with sphinx-needs < 7.

The [needs.global_options] section defines default field values for all needs. Each key is a field name, with a default value and optional predicates for conditional overrides.

Note

The needs_global_options format was changed in sphinx-needs 5.1 to be more explicit (using default/predicates keys). The older tuple-based format from sphinx-needs < 5.1 is no longer supported.

# Simple default
[needs.global_options.status]
default = "open"

# Default with conditional predicates
[needs.global_options.priority]
default = "medium"
predicates = [
  ["type == 'req'", "high"],
  ["status == 'closed'", "low"]
]

default: The value applied when the field is not explicitly set on a need.
predicates: A list of [filter_expression, value] pairs. Each filter expression is evaluated against the need; the first matching predicate’s value is used instead of the default. Filter expressions can reference need fields, filter_data variables, and the top-level build_tags list.

variant_options¶

Deprecated since version 0.25.0: The variant_options list (needs_variant_options in sphinx-needs) was deprecated in sphinx-needs 7.0. Instead, set parse_variants = true on individual fields in [needs.fields]:

[needs.fields.status]
parse_variants = true

[needs.fields.priority]
parse_variants = true

The variant_options list remains supported for backward compatibility with sphinx-needs < 7.

Type: array (default: [])

List of need field names that may contain variant functions for conditional content.

variant_options = ["status", "priority", "assignee"]