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 _images/arrow-right-circle.svg
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

The requirement Sliced Bread (roles_req_1) is the most important one.
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

New 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

Requirement: Butter on Bread roles_req_2 _images/arrow-right-circle.svg
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

New in version 0.1.25.

: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

New 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

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 _images/arrow-right-circle.svg
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 _images/arrow-right-circle.svg
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

@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 

impl_my_car_1 --> my_car_1

@enduml

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

ID

Title

Incoming

Outgoing

impl_my_car_1

Build awesome car

my_car_1

Car must be awesome

→ my_car_1.1

→  A top speed of 300 km/h

→ my_car_1.2

→  An acceleration of 200 m/s² or much much more

→ my_car_1.awesome_3

→  a turbo button

need_count

New 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

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

All needs: 229
Specification needs: 42
Open specification needs: 9
Needs with tag test: 2
Needs with title longer 10 chars: 194
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

New 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

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

Result

21.4 % of our specifications are open.

need_func

New in version 0.6.3.

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.