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 whose :delete: option is truthy (empty, true or yes) is removed entirely, as Sphinx-Needs removes it: nothing is rendered for it, and nothing written inside it — a nested need, a label, an included file’s content — takes effect. An invalid value warns (needs.invalid_delete_option) and removes the need the same way. In the editor the whole directive fades (needs.deleted), as a falsy if does.

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.

Linking to a view¶

The view directives that accept :name: — needflow and needgantt — register the name as a stable cross-reference target, so another page can :ref: straight to that chart:

.. needgantt:: Delivery plan
   :name: delivery-plan

..  and, from anywhere in the project:

See the :ref:`delivery-plan` chart.

In a built site the name becomes an id on the view (normalised the usual way — Delivery Plan becomes delivery-plan), with a ¶ permalink in the caption when the view renders one. A view with no :name: gets no anchor and no permalink, and ubCode never mints the positional id a Sphinx-Needs build does.

Two edges are worth knowing before you rely on it:

A name whose slug is empty still anchors — but not readably. By default ([parse] id_style = "github") a name in any script keeps its letters (:name: 交付计划 anchors at #交付计划), so only a name of punctuation or emoji slugs to nothing. Under id_style = "docutils" the slug drops everything that is not an ASCII letter or digit, so a name written in a non-Latin script slugs to nothing too. The view then takes the page’s shared id1 / id2 counter instead, exactly as a Sphinx build does, and :ref: reaches it. What you lose is the readable URL: #id1 says nothing about what it points at, and it moves if you add another such element earlier on the page. So name the view delivery-plan and write the display text you want: :ref:`交付计划 <delivery-plan>`.
A needflow shows its caption only when it draws a diagram, so a named one whose filter matched nothing keeps its id but shows no ¶. A needgantt draws its caption in every state, so its ¶ is always there.

See Anchors on views and diagrams for the whole rule.

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.