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>`.
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.
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`
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`.
My new car must be the fastest on the world. Therefor it shall have: And we also need –> a turbo button awesome_3! |
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"]
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 |
|---|---|---|---|
Car must be awesome |
|||
→ A top speed of 300 km/h |
|||
→ An acceleration of 200 m/s² or much much more |
|||
→ 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`
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 ( |
The string itself ( |
Integer / float ( |
Its |
Boolean ( |
|
Array ( |
The elements joined into a comma-separated string ( |
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.