Roles¶

You can use Roles to get short information of needs inside single sentences.

Example

My specification :need:`my_spec` is used to fulfill requirements :need_incoming:`my_spec`

need¶

The role :need: will add title, id and a link to the need.

We use it to reference an existing need, without the need to keep title and link location manually in sync.

With [[ and ]] you can refer to defined and set extra options.

Example¶

Requirement: Sliced Bread roles_req_1

status: open value: 20 unit: slices links incoming: roles_req_2

Example

The requirement :need:`roles_req_1` is the most important one.

But we can also set :need:`a custom link name <roles_req_1>`.

And we can change the text even more e.g. :need:`[[value]] [[unit]] of [[title]] ([[id]] [[status]]) <roles_req_1>`.

Result

need_outgoing¶

:need_outgoing: adds a list of all outgoing links of the given need. The list contains the need IDs only, no title or any other information is printed.

Example¶

Requirement: Butter on Bread roles_req_2

links outgoing: roles_req_1

Example

To get butter on our bread, we need to fulfill :need_outgoing:`roles_req_2`

Result

To get butter on our bread, we need to fulfill roles_req_1

need_incoming¶

:need_incoming: prints a list of IDs of needs which have set outgoing links to the given need.

Example¶

Example

The realisation of **Sliced Bread** is really important because the needs :need_incoming:`roles_req_1` are based on
it.

Result

The realisation of Sliced Bread is really important because the needs roles_req_2 are based on it.

need_part / np¶

You can use :need_part: or as shortcut :np: inside needs to set a sub-id for a specific sentence/part. This sub-ids can be linked and referenced in other need functions like links and co.

The used need_part id can be freely chosen, but should not contain any whitespaces or dots.

Example¶

Example

.. req:: Car must be awesome
   :id: my_car_1
   :tags: car
   :status: open

   My new car must be the fastest on the world. Therefor it shall have:

   * :need_part:`(1)A top speed of 300 km/h`
   * :np:`(2) An acceleration of 200 m/s² or much much more`

   And we also need --> :np:`(awesome_3) a turbo button`!


.. spec:: Build awesome car
   :id: impl_my_car_1
   :links: my_car_1.1, my_car_1.2

   Requirements :need:`my_car_1.1` and :need:`my_car_1.2` are no problem and can
   be realised by doing rocket science.

   But no way to get :need:`my_car_1.awesome_3` realised.


Reference to a part of a need from outside need scope: :need:`my_car_1.2`.

Result

Requirement: Car must be awesome my_car_1

status: open tags: car links incoming: impl_my_car_1

My new car must be the fastest on the world. Therefor it shall have: A top speed of 300 km/h 1 An acceleration of 200 m/s² or much much more 2 And we also need –> a turbo button awesome_3!

Specification: Build awesome car impl_my_car_1

tags: car links outgoing: my_car_1, my_car_1.1, my_car_1.2

Requirements A top speed of 300 km/h (my_car_1.1) and An acceleration of 200 m/s... (my_car_1.2) are no problem and can be realised by doing rocket science. But no way to get a turbo button (my_car_1.awesome_3) realised.

Reference to a part of a need from outside need scope: An acceleration of 200 m/s... (my_car_1.2).

Presentation in needflow

Links to need_parts are shown as dotted line to the upper need inside needflow diagrams. They are also getting the part_id as link description.

Example

.. needflow::
   :filter: id in ["my_car_1","impl_my_car_1"]

Result

Presentation in needtable

Please see show_parts of needtable configuration documentation.

Example

.. needtable::
   :style: table
   :filter: 'car' in tags and is_need
   :show_parts:
   :columns: id, title, incoming, outgoing

Result

need_count¶

Counts found needs for a given filter and shows the final amount.

The content of the role must be a valid filter-string as used e.g. by needlist in the :filter: option. See Filter string for more information.

Example¶

Example

All needs: :need_count:`True`
Specification needs: :need_count:`type=='spec'`
Open specification needs: :need_count:`type=='spec' and status=='open'`
Needs with tag *test*: :need_count:`'test' in tags`
Needs with title longer 10 chars: :need_count:`search("[\\w\\s]{10,}", title)`
All need_parts: :need_count:`is_part`
All needs containing need_parts: :need_count:`is_need and len(parts)>0`

Result

Ratio¶

To calculate the ratio of one filter to another filter, you can define two filters separated by _?_ (question mark surrounded by one space on each side).

Example

:need_count:`status = open and type == "spec" ? type == "spec"` % of our specifications are open.

Result

23.3 % of our specifications are open.

need_func¶

Executes Dynamic functions and uses the return values as content.

Example

A nice :need_func:`[[echo("first")]] test` for need_func.

Result

A nice first test for need_func.