Roles¶

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

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 1

.. req:: Sliced Bread
   :id: roles_req_1
   :status: open
   :value: 20
   :unit: slices

| 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>`.

Requirement: Sliced Bread roles_req_1

status: open

value: 20

unit: slices

links incoming: roles_req_2

The requirement Sliced Bread (roles_req_1) is the most important one.
But we can also set a custom link name (roles_req_1).
And we can change the text even more e.g. 20 slices of Sliced Bread (roles_req_1 open).

Note

You can customize the string representation by using the configuration parameters needs_role_need_template and needs_role_need_max_title_length. If we find a [[ in the customized string, we handle it according to Python’s { .format() function. Please see https://pyformat.info/ for more information. RST-attributes like **bold** are not supported.

Warning

If you refer to an external need, the algorithm is different and you will only get the need id as link text.

need_outgoing¶

Added in version 0.1.25.

: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 2

.. req:: Butter on Bread
   :id: roles_req_2
   :links: roles_req_1

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

Requirement: Butter on Bread roles_req_2

links outgoing: roles_req_1

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

need_incoming¶

Added in version 0.1.25.

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

Example 3

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

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

need_part / np¶

Added in version 0.3.0.

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 4

.. 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`.

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

links outgoing: 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 5

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

@startuml

' Nodes definition

node "<size:12>Requirement</size>\n**Car must be**\n**awesome**\n<size:10>my_car_1</size>" as my_car_1 [[../roles.html#my_car_1]] #BFD8D2{
'parts:
}
node "<size:12>Specification</size>\n**Build awesome**\n**car**\n<size:10>impl_my_car_1</size>" as impl_my_car_1 [[../roles.html#impl_my_car_1]] #FEDCD2

' Connection definition

@enduml

Presentation in needtable

Please see show_parts of needtable configuration documentation.

Example 6

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

ID	Title	Incoming
my_car_1	Car must be awesome	impl_my_car_1
→ my_car_1.1	→ A top speed of 300 km/h	impl_my_car_1
→ my_car_1.2	→ An acceleration of 200 m/s² or much much more	impl_my_car_1
→ my_car_1.awesome_3	→ a turbo button

need_count¶

Added in version 0.3.1.

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 7

| 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`

All needs: 232
Specification needs: 39
Open specification needs: 8
Needs with tag test: 3
Needs with title longer 10 chars: 197
All need_parts: 10
All needs containing need_parts: 4

Note

If backslashes \ are used inside the regex function search, please make sure to double them as in python one \ needs to be represented by \\.

Note

need_count executes the given filter on needs and need_parts! So if you use need_part / np , the result may contain the amount of found needs and found need_parts. To avoid this, add is_need or is_part to your filter.

Ratio¶

Added in version 0.5.3.

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 8

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

0.0 % of our specifications are open.

need_func¶

Deprecated since version 3.1.0: Use ndf instead.

ndf¶

Added in version 3.1.0.

Executes a need dynamic function and uses the return values as content.

Example 9

A nice :ndf:`echo("first test")` for dynamic functions.

A nice first test for dynamic functions.