Needs¶

Every need type you declare in Need types (req, spec, and any others in your needs.types) becomes a directive of the same name. In the preview those directives render as need cards — a header, a meta table, and the need’s body.

The card itself is described in the Need cards section of RST preview; this page covers the authoring surface — how you write the directive and what each part maps to.

This reference describes the Rendered preview mode; in Structural mode every directive and role renders as a uniform placeholder (see Authoring).

Writing a need¶

A need is written as a directive whose name is the need type, with the title as its argument, options for the need’s fields and links, and the body as free content:

.. req:: Bootloader validates firmware signature
   :id: REQ_001
   :links: SPEC_014

   The bootloader must verify the firmware signature
   before handing over control.

The card that renders from this shows three parts:

a header with the need’s type, title, and id;
a meta table listing the remaining fields and links (here, the links option);
the body, rendered as normal markup — it may itself contain nested needs, references, and emphasis.

The :id: option is optional. When you omit it, an id is generated automatically from the title together with the type’s prefix and your configuration, so the card always has a stable id to show.

The meta table stays deliberately light. Fields with empty values are skipped, and the core identity fields already shown in the header (the type, title, and id) are not repeated in the table, so it lists only what you actually wrote.

Hydration¶

A card renders in two stages, matching the general hydration behaviour of the preview.

Before the project has been indexed, the card shows the values exactly as written in the directive, and any links are shown as plain text.

Once a background indexing pass completes, the card is hydrated: field values become the effective, post-needextend state, outgoing links become clickable cross-references, and a “links back” row lists the needs that link to this one — information that does not appear in the source file at all (see the Need cards section of RST preview). The card re-hydrates after each background indexing pass, so cross-project facts settle on the next update rather than instantly per keystroke.

The hydrated meta table shows your authored fields plus anything needextend changed — not every config-default field that a full Sphinx-Needs build would list. This keeps the authored rows visible rather than buried; see Differences from a Sphinx build for the full comparison.

A need marked with a truthy :delete: option is dropped from the index, and its card renders empty.

Conditional needs¶

Like any other content, a need can be wrapped in the if directive so that it is included only for matching variants:

.. if:: var.platform == "windows"

   .. req:: Windows power management
      :id: REQ_WIN_PM

      This requirement only exists in the Windows variant.

The if directive is not specific to needs — it conditionally includes any block of content. For the full directive reference, the variant role, and variant field values, see Variants.

Need references¶

To point at a need from prose — rather than defining one — use the need reference roles (need, need_incoming, need_outgoing, need_part). These are covered, together with how they hydrate into clickable links, under Roles.