1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
.. _roles:
Roles
=====
You can use Roles to get short information of needs inside single sentences.
.. _role_need:
.. _needref:
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 :ref:`extra options <needs_extra_options>`.
.. need-example::
.. 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>`.
.. note::
You can customize the string representation by using the
configuration parameters :ref:`needs_role_need_template` and
:ref:`needs_role_need_max_title_length`.
If we find a ``[[`` in the customized string, we handle it
according to Python's ``{`` `.format() <https://docs.python.org/3.4/library/functions.html#format>`_
function.
Please see https://pyformat.info/ for more information.
RST-attributes like ``**bold**`` are **not** supported.
.. warning::
If you refer to an :ref:`external need <needs_external_needs>`, the algorithm is different
and you will only get the need id as link text.
.. _role_need_outgoing:
need_outgoing
-------------
.. versionadded:: 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.
.. need-example::
.. 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`
.. _role_need_incoming:
need_incoming
-------------
.. versionadded:: 0.1.25
``:need_incoming:`` prints a list of IDs of needs which have set outgoing links to the given need.
.. need-example::
The realisation of **Sliced Bread** is really important because the needs :need_incoming:`roles_req_1` are based on
it.
.. _need_part:
need_part / np
----------------
.. versionadded:: 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.
.. need-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`.
**Presentation in needflow**
Links to need_parts are shown as dotted line to the upper need inside :ref:`needflow` diagrams.
They are also getting the part_id as link description.
.. need-example::
.. needflow::
:filter: id in ["my_car_1","impl_my_car_1"]
**Presentation in needtable**
Please see :ref:`needtable_show_parts` of :ref:`needtable` configuration documentation.
.. need-example::
.. needtable::
:style: table
:filter: 'car' in tags and is_need
:show_parts:
:columns: id, title, incoming, outgoing
.. _need_count:
need_count
----------
.. versionadded:: 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 :ref:`needlist` in the ``:filter:`` option.
See :ref:`filter_string` for more information.
.. need-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`
.. 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 :ref:`need_part` , 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.
.. _need_count_ratio:
Ratio
~~~~~
.. versionadded:: 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).
.. need-example::
:need_count:`status == open and type == "spec" ? type == "spec"` % of our specifications are open.
.. _need_func:
need_func
---------
.. deprecated:: 3.1.0
Use :ref:`ndf` instead.
.. _ndf:
ndf
---
.. versionadded:: 3.1.0
Executes a :ref:`need dynamic function <dynamic_functions>` and uses the return values as content.
.. need-example::
A nice :ndf:`echo("first test")` for dynamic functions.
|
