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

The possible variables are listed in the configuration documentation for needs_role_need_template.

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.
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. needs_role_need_template is rendered using Jinja syntax. The explicit inline variant :need:`[[...]] <ID>` is also rendered as Jinja, using [[ and ]] as the variable delimiters. RST-attributes like **bold** are not supported.

Warning

If you refer to a whole external need, the algorithm is different and you will only get the need id as link text. A reference to a part of an external need, :need:`EXT_ID.part`, is written as one to a part of a need of the project, with the part’s text and EXT_ID.part (or the text given in the role). It links the part’s anchor on the external page when the need’s url ends in its id, as the default one does, and the need’s url otherwise (see target_url in needs_external_needs).

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

Outgoing

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

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: 244
Specification needs: 44
Open specification needs: 10
Needs with tag test: 3
Needs with title longer 10 chars: 207
All need_parts: 11
All needs containing need_parts: 5

Note

If backslashes \ are used inside the regex function search, in a role the text loses one level of backslashes before the filter is read, so a backslash of the pattern is written four times there ("\\\\d", as in the example above), or avoided with a character class ("[.]").

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

Changed in version 9.0.0: The need_func role is removed; use ndf instead.

ndf

Added in version 4.0.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.

variant

Added in version 8.2.0.

Resolves a reference into needs_variant_data and is immediately replaced during parsing by a text node holding the looked-up value.

The role content is a dotted path into the configured variant data, rooted at var (the var root is implicit and must not be written).

Given the configuration:

needs_variant_data = {
    "platform": "arm",
    "build": {"opt_level": 2},
}

then in a document:

Platform: :variant:`platform`
Optimisation level: :variant:`build.opt_level`

resolves to arm and 2 respectively.

Type handling

The role always produces a single text node. The resolved value is serialised to text as follows:

Variant data value

Rendered text

String ("arm")

The string itself (arm).

Integer / float (2, 1.5)

Its str() form (2, 1.5).

Boolean (True)

True / False (Python’s str(bool)).

Array (["arm", "x86"])

The elements joined into a comma-separated string (arm, x86).

Mapping ({...})

Not allowed — emits a warning and renders empty text (reference a leaf value instead).

The lookup is a constrained var.* path resolution (the same as used by needs_variant_data field references), not an arbitrary expression: no operators, function calls, or item access are allowed. An invalid reference, an unknown key, or a path that resolves to a mapping emits a needs.variant warning and produces empty text.

Note

The value is resolved at parse time and baked into the document. Changing needs_variant_data triggers a full rebuild so the resolved values stay current, and so does editing the contents of a needs_variant_data_file without changing its path, because the merged data is part of the configuration that is compared between builds.