Need roles

These roles point at needs from running text: a reference to a need or a need part, a count of the needs a filter selects, and the value a dynamic function computes. ubCode resolves them against the project’s index, in the editor preview and in its html and pdf builds, so a reference can name a need defined on any page. The specimens point at the needs on Writing needs. How they become links in the preview is under the cross-reference roles.

Need references

The :need: role links to a need by its id. On its own it reads as the need’s title followed by its id; with text of your own before the id in angle brackets, it reads as that text.

reStructuredText

Need references

:need:`EX_REQ_EXPORT` is refined by
:need:`the one-row specification <EX_SPEC_EXPORT>`.

Export the report as CSV (EX_REQ_EXPORT) is refined by the one-row specification (EX_SPEC_EXPORT).

MyST

{need}`EX_REQ_MYST_EXPORT` is refined by
{need}`the one-row specification <EX_SPEC_MYST_EXPORT>`.

The MyST form renders live in the MyST need references.

Note

With text of your own, a Sphinx-Needs build appends the id — the one-row specification (EX_SPEC_EXPORT) — where ubCode shows the text alone (see the need-role differences).

Need parts

A need’s content marks its parts with the :need_part: role, or its short form :np: (see the need-part specimen). :need: reaches a part by the need’s id, a dot, and the part’s id.

reStructuredText

A reference to a need part

The header row is described in :need:`EX_REQ_EXPORT_HEADER.columns`.

The header row is described in starts with a row naming th... (EX_REQ_EXPORT_HEADER.columns).

MyST

The header row is described in {need}`EX_REQ_MYST_EXPORT_HEADER.columns`.

The MyST form renders live in the MyST need parts.

Note

ubCode links a part reference to the whole need and reads it as the need’s title and id; a Sphinx-Needs build links the part itself and reads it as the part’s text and full id (see the need-role differences).

Counting needs

The :need_count: role shows how many needs a filter selects. Two filters joined by ? show the first count as a percentage of the second. The filters here select the two test specimens of Writing needs, whose ids end in EXPORT, so a test need added anywhere else in the project leaves the counts alone.

reStructuredText

Need counts

The specimens hold :need_count:`type == "test" and id.endswith("EXPORT")` tests,
and :need_count:`type == "test" and id.endswith("EXPORT") and status == "passed" ? type == "test" and id.endswith("EXPORT")`
per cent of them have passed.

The specimens hold 2 tests, and 100.0 per cent of them have passed.

MyST

The specimens hold {need_count}`type == "test" and id.endswith("EXPORT")` tests,
and {need_count}`type == "test" and id.endswith("EXPORT") and status == "passed" ? type == "test" and id.endswith("EXPORT")`
per cent of them have passed.

The MyST form renders live in the MyST need counts.

Note

ubCode counts needs and not their parts, where a Sphinx-Needs build counts both; these tests have no parts, so the two agree (see the need-count differences).

Incoming and outgoing links

In a Sphinx-Needs build, :need_incoming: lists the needs that link to the need it names, and :need_outgoing: the needs it links to, each as a link. ubCode does not draw these lists yet: it draws each role as a link to the named need itself, as :need: does, so this specimen shows its source only (see the need-role differences).

reStructuredText

The export requirement is linked from :need_incoming:`EX_REQ_EXPORT`,
and the CSV writer links to :need_outgoing:`EX_IMPL_EXPORT`.

MyST

The export requirement is linked from {need_incoming}`EX_REQ_EXPORT`,
and the CSV writer links to {need_outgoing}`EX_IMPL_EXPORT`.

A card lists the same links in its own rows: the specimen requirement’s card shows each need that links to it as an incoming link.

Dynamic functions

The :ndf: role runs a dynamic function and shows the value it returns. Inside a need’s content, the function reads that need: here copy returns the need’s own status.

reStructuredText

A dynamic function

.. impl:: CSV quoting helper
   :id: EX_IMPL_EXPORT_HELPER
   :status: in review
   :links: EX_SPEC_EXPORT_QUOTING

   This helper is :ndf:`copy("status")`.

Implementation: CSV quoting helper EX_IMPL_EXPORT_HELPER

status: in review links outgoing: EX_SPEC_EXPORT_QUOTING

This helper is in review.

MyST

```{impl} CSV quoting helper
:id: EX_IMPL_MYST_EXPORT_HELPER
:status: in review
:links: EX_SPEC_MYST_EXPORT_QUOTING

This helper is {ndf}`copy("status")`.
```

The MyST form renders live in the MyST dynamic function.

ubCode evaluates every built-in dynamic function of Sphinx-Needs; the dynamic-function differences list what it does not evaluate.