Roles

Roles can be used to get short information of needs inside single sentences:

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

Available roles:

need

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

It is mostly used to reference an existing need, without the need to keep title and link location manually in sync.

Example

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

Result: The requirement Sliced Bread (roles_req_1) is the most important one.

Note

The string representation can be easily customized by using the configuration parameter needs_role_need_template.

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
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 IDs of needs, which have set outgoing links to the given need.

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.

:need_part: or as shortcut :np: can be used 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

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

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

  • A topspeed 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

Requirements A topspeed 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.

.. needflow::
   :filter: id in ["my_car_1","impl_my_car_1"]
_images/need_part_as_flow.png

Presentation in needtable

Please see show_parts pf needtable configuration documentation.

.. needtable::
   :style: table
   :filter: 'car' in tags
   :show_parts:
   :columns: id, title, incoming, outgoing
ID Title Incoming Outgoing
my_car_1 → Car must be awesome impl_my_car_1
→ my_car_1.1 → A topspeed of 300 km/h impl_my_car_1
→ my_car_1.awesome_3 →  a turbo button
→ my_car_1.2 →  An acceleration of 200 m/s or much much more impl_my_car_1
impl_my_car_1 → Build awesome car my_car_1; my_car_1.1; my_car_1.2
→ my_car_1.1 → A topspeed of 300 km/h impl_my_car_1
→ my_car_1.awesome_3 →  a turbo button
→ my_car_1.2 →  An acceleration of 200 m/s or much much more impl_my_car_1

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

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: 54
Specification needs: 17
Open specification needs: 2
Needs with tag test: 2
Needs with title longer 10 chars: 43
All need_parts: 6
All needs containing need_parts: 2

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 is, add is_need or is_part to your filter.