Writing needs¶

Every need type your project declares under needs.types becomes a directive of the same name. The directive’s argument is the need’s title, its options set the need’s id, fields and links, and its body is the need’s content, written in ordinary markup. ubCode reads each need into the project’s index — the one needs.json, filters and views read — and draws it as a need card in the editor preview and in its html and pdf builds. The card is ubCode’s own design rather than the table a Sphinx-Needs build draws; the need-card differences list where the two differ.

The specimens use the four need types these docs declare for them, req, spec, impl and test, and every specimen need’s id starts EX_.

A need and its links¶

A requirement, the specification that refines it, the implementation of that specification, and the test of the implementation. Each has a title, an :id: and a :status:, and each one after the first links to the one before it with :links:.

reStructuredText

Four linked needs

.. req:: Export the report as CSV
   :id: EX_REQ_EXPORT
   :status: open
   :tags: export, reporting

   A user can save the report as a CSV file.

.. spec:: One row per record
   :id: EX_SPEC_EXPORT
   :status: open
   :links: EX_REQ_EXPORT

   The file has a header row, then one row per record.

.. impl:: CSV writer
   :id: EX_IMPL_EXPORT
   :status: done
   :links: EX_SPEC_EXPORT

   The writer emits the rows in the order the report shows them.

.. test:: CSV writer test
   :id: EX_TEST_EXPORT
   :status: passed
   :links: EX_IMPL_EXPORT

   Exports a two-record report and compares the file with the expected one.

Requirement: Export the report as CSV EX_REQ_EXPORT

status: open

tags: export, reporting

links incoming: EX_SPEC_EXPORT, EX_SPEC_EXPORT_FILENAME, EX_SPEC_EXPORT_QUOTING

A user can save the report as a CSV file.

Specification: One row per record EX_SPEC_EXPORT

status: open

links outgoing: EX_REQ_EXPORT

links incoming: EX_IMPL_EXPORT

The file has a header row, then one row per record.

Implementation: CSV writer EX_IMPL_EXPORT

status: done

links outgoing: EX_SPEC_EXPORT

links incoming: EX_TEST_EXPORT

The writer emits the rows in the order the report shows them.

Test Case: CSV writer test EX_TEST_EXPORT

status: passed

links outgoing: EX_IMPL_EXPORT

Exports a two-record report and compares the file with the expected one.

MyST

```{req} Export the report as CSV
:id: EX_REQ_MYST_EXPORT
:status: open
:tags: export, reporting

A user can save the report as a CSV file.
```

```{spec} One row per record
:id: EX_SPEC_MYST_EXPORT
:status: open
:links: EX_REQ_MYST_EXPORT

The file has a header row, then one row per record.
```

```{impl} CSV writer
:id: EX_IMPL_MYST_EXPORT
:status: done
:links: EX_SPEC_MYST_EXPORT

The writer emits the rows in the order the report shows them.
```

```{test} CSV writer test
:id: EX_TEST_MYST_EXPORT
:status: passed
:links: EX_IMPL_MYST_EXPORT

Exports a two-record report and compares the file with the expected one.
```

The MyST form renders live in the MyST linked needs.

:id:: The need’s id, unique in the project. It is what links, references and filters name the need by.
:status:: The need’s status, as free text.
:tags:: A comma-separated list of tags.
:links:: A comma-separated list of the ids this need links to. Each need it names lists the link back as an incoming link. Every link type your project declares under needs.links is an option of its own, written the same way.

Every field your project declares under needs.fields is an option too; the options table below lists the rest. A card shows the fields you wrote, skipping empty ones, and the need’s outgoing and incoming links.

Generated ids¶

A need written without :id: gets an id generated from its type’s prefix and a hash of its title, the same one in ubCode and in a Sphinx-Needs build: in a project that does not require ids and keeps the default id length, the need below is EX_REQ_A7921. These docs require an id on every need (needs.id_required), so here the need is reported and left out of the project’s index, which is why this specimen shows its source only.

reStructuredText

.. req:: Export the report as CSV

   A user can save the report as a CSV file.

MyST

```{req} Export the report as CSV
A user can save the report as a CSV file.
```

With ids required, ubCode reports such a need as needs.id_required (No id provided for need directive), and a Sphinx build as Need could not be created: No ID defined, but ‘needs_id_required’ is set to True.

Need parts¶

The :need_part: role, or its short form :np:, marks a part of a need’s content: the part’s id in parentheses, then its text. The part’s full id is the need’s id, a dot, and the part’s id, and both :links: and the need roles can name it.

reStructuredText

A need with two parts

.. req:: Report header
   :id: EX_REQ_EXPORT_HEADER
   :status: open

   The file :need_part:`(columns)starts with a row naming the columns`
   and :np:`(encoding)is encoded as UTF-8`.

Requirement: Report header EX_REQ_EXPORT_HEADER

status: open

The file starts with a row naming the columns columns and is encoded as UTF-8 encoding.

MyST

```{req} Report header
:id: EX_REQ_MYST_EXPORT_HEADER
:status: open

The file {need_part}`(columns)starts with a row naming the columns`
and {np}`(encoding)is encoded as UTF-8`.
```

The MyST form renders live in the MyST need parts.

Note

ubCode records each part — it is in needs.json, and a link or reference reaches it — but draws the role as a chip showing its source, not yet as the part’s text and id (see the need-role differences).

Card options¶

Three options change how a need’s card is drawn. :collapse: starts the card’s fields and links closed, behind a disclosure you open; :layout: picks the card’s design; :style: adds style names to the card.

reStructuredText

Card options

.. spec:: Quote fields that hold a comma
   :id: EX_SPEC_EXPORT_QUOTING
   :status: open
   :links: EX_REQ_EXPORT
   :collapse: true

   A field that holds a comma is written in double quotes.

.. spec:: Name the file after the report
   :id: EX_SPEC_EXPORT_FILENAME
   :status: open
   :links: EX_REQ_EXPORT
   :layout: complete
   :style: green_border

   The file takes the report's title as its name.

Specification: Quote fields that hold a comma EX_SPEC_EXPORT_QUOTING

status: open

links outgoing: EX_REQ_EXPORT

links incoming: EX_IMPL_EXPORT_HELPER, EX_IMPL_EXPORT_QUOTING

A field that holds a comma is written in double quotes.

EX_SPEC_EXPORT_FILENAME	Name the file after the report		Specification
status: open		links outgoing: EX_REQ_EXPORT
The file takes the report’s title as its name.
layout: complete			style: green_border

MyST

```{spec} Quote fields that hold a comma
:id: EX_SPEC_MYST_EXPORT_QUOTING
:status: open
:links: EX_REQ_MYST_EXPORT
:collapse: true

A field that holds a comma is written in double quotes.
```

```{spec} Name the file after the report
:id: EX_SPEC_MYST_EXPORT_FILENAME
:status: open
:links: EX_REQ_MYST_EXPORT
:layout: complete
:style: green_border

The file takes the report's title as its name.
```

The MyST form renders live in the MyST card options.

:layout: names one of ubCode’s built-in card designs or one your project defines under [needs.card_layouts]; complete adds a footer that repeats the layout and style. Unset, a card takes the project’s needs.default_layout. :style: is a comma-separated list of names, and ubCode styles the ones a Sphinx-Needs build’s stylesheet defines, green_border among them. How ubCode’s designs and styles compare with a Sphinx-Needs build’s is in the need-card differences.

Note

The PDF prints every card open, whatever its :collapse: says.

Title from content¶

With :title_from_content: and no argument, the need takes its title from the first line of its content, up to its first full stop. needs.title_from_content turns this on for every need in the project.

reStructuredText

A title from the content

.. impl::
   :id: EX_IMPL_EXPORT_QUOTING
   :status: open
   :links: EX_SPEC_EXPORT_QUOTING
   :title_from_content:

   Quote a field when it holds a comma.
   The writer checks every field before it writes the row.

Implementation: Quote a field when it holds a comma EX_IMPL_EXPORT_QUOTING

status: open

links outgoing: EX_SPEC_EXPORT_QUOTING

Quote a field when it holds a comma. The writer checks every field before it writes the row.

MyST

```{impl}
:id: EX_IMPL_MYST_EXPORT_QUOTING
:status: open
:links: EX_SPEC_MYST_EXPORT_QUOTING
:title_from_content:

Quote a field when it holds a comma.
The writer checks every field before it writes the row.
```

The MyST form is shown as source only (see the note below).

Note

In a MyST document ubCode does not take the title from the content yet: it reports needs.title (:title_from_content: set, but the content does not start with a paragraph) and leaves the need untitled, where a Sphinx build takes the title as it does in reStructuredText (see the need-card differences).

Hidden and deleted needs¶

Two options change whether a need appears on the page, each in its own way, so this specimen shows their source only.

reStructuredText

.. spec:: Compress large reports
   :id: EX_SPEC_EXPORT_COMPRESS
   :hide:

   A report over one megabyte is written as a ZIP archive.

.. spec:: Export as a spreadsheet
   :id: EX_SPEC_EXPORT_SHEET
   :delete: true

   Superseded by the CSV export.

MyST

```{spec} Compress large reports
:id: EX_SPEC_EXPORT_COMPRESS
:hide:

A report over one megabyte is written as a ZIP archive.
```

```{spec} Export as a spreadsheet
:id: EX_SPEC_EXPORT_SHEET
:delete: true

Superseded by the CSV export.
```

A need with :hide: stays in the index, and ubCode draws its card collapsed to its header line in the editor preview and in its html build; its pdf build prints the card open, body included, unless build.pdf.hidden_needs is "collapsed", which prints the header line alone; a Sphinx-Needs build draws nothing for it (see the need-card differences).

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.

Options¶

Every option of the need directive, and what ubCode does with it. Honoured options act as in a Sphinx-Needs build, with the differences the linked entries list; parsed only options are accepted without a finding and change nothing about the need. The keys that configure needs project-wide are in the needs configuration reference.

Option	What it sets	ubCode
`:id:`	The need’s id; generated when it is missing and `needs.id_required` is off.	Honoured
`:status:`	The need’s status.	Honoured
`:tags:`	The need’s tags, comma-separated.	Honoured
`:links:`, and each link type under `needs.links`	The needs (or need parts) this need links to, comma-separated.	Honoured
Each field under `needs.fields`	That field’s value.	Honoured
`:title_from_content:`	Take the title from the content’s first line.	Honoured in reStructuredText; not yet in MyST (register)
`:collapse:`	Start the card’s fields and links closed.	Honoured; printed open in the PDF
`:layout:`	The card’s design.	Honoured, as ubCode’s card designs (register)
`:style:`	Style names added to the card.	Honoured
`:hide:`	Hide the need’s card.	Drawn as a card collapsed to its header line, printed open in the PDF (register)
`:delete:`	Remove the need and everything written inside it.	Honoured
`:jinja_content:`	Render the content as a Jinja template.	Parsed only (register)
`:template:`, `:pre_template:` and `:post_template:`	Render the need through a template file.	Parsed only (register)
`:constraints:`	Constraints from `needs_constraints` to check the need against.	Parsed only (register)