Creates a need object with a specified type. You can define the type using the correct directive, like .. req::
or .. test::
.
.. req:: User needs to login
:id: ID123
:status: open
:tags: user;login
:collapse: false
Our users needs to get logged in via our login forms on **/login.php**.
Output
User needs to login
Our users needs to get logged in via our login forms on /login.php.
The code example above creates a new requirement, with a title, content, given id, a status and several tags.
All the options for the requirement directive ( req
) are optional, but you must set a title as an argument (i.e. if you do not specify needs_title_from_content
in the conf.py file).
Note
By default, the above example works also with .. spec::
, .. impl::
, .. test::
and all other need types, which are configured via needs_types
.
1.0.2
Needs variants add support for variants handling on need options. The support for variants options introduce new ideologies on how to set values for need options.
To implement variants options, you can set a need option to a variant definition or multiple variant definitions. A variant definition can look like var_a:open
or ['name' in tags]:assigned
.
A variant definition has two parts: the rule or key and the value. For example, if we specify a variant definition as var_a:open
, then var_a
is the key and open
is the value. On the other hand, if we specify a variant definition as ['name' in tags]:assigned
, then ['name' in tags]
is the rule and assigned
is the value.
- Variants gets checked from left to right.
- When evaluating a variant definition, we use data from the current need object, Sphinx-Tags, and
needs_filter_data
as the context for filtering. - You can set a need option to multiple variant definitions by separating each definition with either the
,
or;
symbol, likevar_a:open; ['name' in tags]:assigned
. With multiple variant definitions, we set the first matching variant as the need option's value. - When you set a need option to multiple variant definitions, you can specify the last definition as a default "variant-free" option which we can use if no variant definition matches. Example; In this multi-variant definitions,
[status in tags]:added; var_a:changed; unknown
, unknown will be used if none of the other variant definitions are True. - If you prefer your variant definitions to use rules instead of keys, then you should put your filter string inside square brackets like this:
['name' in tags]:assigned
. - For multi-variant definitions, you can mix both rule and variant-named options like this:
[author["test"][0:4] == 'me']:Me, var_a:Variant A, Unknown
To implement variants options, you must configure the following in your conf.py
file:
needs_variants
needs_variant_options
There are various use cases for variants options support.
In this example, you set the needs_variants
configuration that comprises pre-defined variants assigned to "filter strings". You can then use the keys in your needs_variants
as references when defining variants for a need option.
In conf.py
:
needs_variants = {
"var_a": "'var_a' in sphinx_tags" # filter_string
"var_b": "assignee == 'me'"
}
In your .rst
file:
.. req:: Example
:id: VA_001
:status: var_a:open, var_b:closed, unknown
From the above example, if a need option has variants defined, then we get the filter string from our needs_variants
configuration and evaluate it. If a variant definition is true, then we set the need option to the value of the variant definition.
In this example, you can use the filter string directly in the need option's variant definition.
In your .rst
file:
.. req:: Example
:id: VA_002
:status: ['var_a' in tags]:open, [assignee == 'me']:closed, unknown
From the above example, we evaluate the filter string in our variant definition without referring to needs_variants
. If a variant definition is true, then we set the need option to the value of the variant definition.
In this example, you can use defined tags (via the -t command-line option or within conf.py, see here) in the need option's variant definition.
First of all, define your Sphinx-Tags using either the -t
command-line sphinx-build
option:
sphinx-build -b html -t tag_a . _build
or using the special object named tags
which is available in your Sphinx config file (conf.py
file):
tags.add("tag_b") # Add "tag_b" which is set to True
In your .rst
file:
.. req:: Example
:id: VA_003
:status: [tag_a and tag_b]:open, closed
From the above example, if a tag is defined, the plugin can access it in the filter context when handling variants. If a variant definition is true, then we set the need option to the value of the variant definition.
Note
Undefined tags are false and defined tags are true.
Below is an implementation of variants for need options:
.. req:: Variant options
:id: VA_004
:status: ['variants' in tags and not collapse]:enabled, disabled
:tags: variants;support
:collapse: true
Variants for need options in action
Variant options
Variants for need options in action
A need objects can also define it's own PlantUML representation. Therefore Sphinx-Needs looks for the needuml
directive inside the content and stores its PlantUML code under given key from needuml
directive under the option name arch
.
This diagram data can then be used in other needuml
calls to combine and reuse PlantUML elements.
{% raw %}
.. spec:: Interfaces
:id: SP_INT
:status: open
This are the provided interfaces:
.. needuml::
circle "Int A" as int_a
circle "Int B" as int_b
circle "Int C" as int_c
Reuse of :need:`SP_INT` inside a :ref:`needuml`:
.. needuml::
allowmixing
{{uml("SP_INT")}}
node "My System" as system
system => int_a
Interfaces
This are the provided interfaces:
circle "Int A" as int_a circle "Int B" as int_b circle "Int C" as int_c
Reuse of SP_INT
inside a needuml
:
allowmixing
{{uml("SP_INT")}} node "My System" as system
system => int_a
{% endraw %}
This simple mechanism is really powerful to design reusable and configurable SW architecture diagrams. For more examples and details, please read needuml
.
The option arch
can be easily used for filtering. For instance to show all need objects, which are representing some kind of a diagram.
.. needtable::
:filter: arch
:style: table
:columns: id, type, title
The given ID must match the regular expression (regex) value for the needs_id_regex
parameter in conf.py. The Sphinx build stops if the ID does not match the regex value.
If you do not specify the id option, we calculate a short hash value based on the title. The calculated value can also include title if needs_id_from_title
is set to True. If you don’t change the title, the id will work for all upcoming documentation generations.
A need can only have one status, and the needs_statuses
configuration parameter may restrict its selection.
You can give multiple tags by separating each with ; symbol, like tag1;tag2;tag3
. White spaces get removed.
The links
option can create a link to one or several other needs, no matter the need type. All you must specify is the ID for the need.
You can easily set links to multiple needs by using ; as a separator.
.. req:: Link example Target
:id: REQ_LINK_1
This is the target for a link. Itself has no link set.
.. req:: Link example Source
:links: REQ_LINK_1
This sets a link to id ``REQ_LINK_1``.
Link example Target
This is the target for a link. Itself has no link set.
Link example Source
This sets a link to id REQ_LINK_1
.
By using needs_extra_links <needs_extra_links>
, you can use the configured link-types to set additional need options.
# conf.py
needs_extra_links = [
{
"option": "blocks",
"incoming": "is blocked by",
"outgoing": "blocks"
},
{
"option": "tests",
"incoming": "is tested by",
"outgoing": "tests",
"copy": False,
"color": "#00AA00"
}
]
.. req:: test me
:id: test_req
A requirement, which needs to be tested
.. test:: test a requirement
:id: test_001
:tests: test_req
Perform some tests
test me
A requirement, which needs to be tested
test a requirement
Perform some tests
There is a :delete: option. If the value of the option is set to true
, the need will be deleted completely from any NeedLists or NeedDicts including the needs.json
file.
This option allows a user to have multiple need-objects with the same id, but only one is shown in the documentation.
If set to false
, the need is not removed.
Allowed values:
true
oryes
or1
false
orno
or0
Default: False
Note
If you delete a need using the :delete: option, the need will not be part of any filter result.
.. req:: First Requirement Need
:id: DELID123
:status: open
:delete: true
Need with ``:delete:`` equal to ``true``.
.. req:: Second Requirement Need
:id: DELID123
:delete: false
Need with ``:delete:`` equal to ``false``.
.. spec:: Nested Need without delete option
:id: DELID124
:tags: nested-del-need
Need with ``:delete:`` option not set.
First Requirement Need
Need with :delete:
equal to true
.
Second Requirement Need
Need with :delete:
equal to false
.
Nested Need without delete option
Need with :delete:
option not set.
There is a :hide: option. If this is set (no value is needed), the need will not be printed in the documentation. But you can use it with need filters.
If set to True, the details section containing status, links or tags is not visible. You can view the details by clicking on the forward arrow symbol near the need title.
If set to False, the need shows the details section.
Allowed values:
- true; yes; 1
- false; no; 0
Default: False
.. req:: Collapse is set to True
:tags: collapse; example
:collapse: True
Only title and content are shown
.. req:: Collapse is set to False
:tags: collapse; example
:collapse: False
Title, tags, links and everything else is shown directly.
Collapse is set to True
Only title and content are shown
Collapse is set to False
Title, tags, links and everything else is shown directly.
The option activates jinja-parsing for the content of a need. If the value is set to true
, you can specify Jinja syntax in the content.
The :jinja_content: option give access to all need data, including the original content and the data in needs_filter_data
.
If you set the option to False, you deactivate jinja-parsing for the need's content.
Allowed values:
true
oryes
or1
false
orno
or0
Default: False
Note
You can set the :jinja_content: option using the needs_global_options
configuration variable. This will enable jinja-parsing for all the need objects in your documentation project.
needs_global_options = {
'jinja_content': 'true'
}
{% raw -%}
.. req:: First Req Need
:id: JINJAID123
:jinja_content: false
Need with ``:jinja_content:`` equal to ``false``.
.. spec:: Nested Spec Need
:id: JINJAID125
:status: open
:tags: user;login
:links: JINJAID126
:jinja_content: true
Nested need with ``:jinja_content:`` option set to ``true``.
This requirement has tags: **{{ tags | join(', ') }}**.
It links to:
{% for link in links %}
- {{ link }}
{% endfor %}
.. spec:: First Spec Need
:id: JINJAID126
:status: open
:jinja_content: true
Need with ``:jinja_content:`` equal to ``true``.
This requirement has status: **{{ status }}**.
{% endraw %}
{% raw -%}
First Req Need
Need with :jinja_content:
equal to false
.
Nested Spec Need
Nested need with :jinja_content:
option set to true
. This requirement has tags: {{ tags | join(', ') }}.
It links to: {% for link in links %} - {{ link }} {% endfor %}
First Spec Need
Need with :jinja_content:
equal to true
. This requirement has status: {{ status }}.
{% endraw %}
0.2.3
When this flag is provided on a need, a title will be derived from the first sentence of the content. If the title or content is not provided then the build process will fail.
The derived title will respect the needs_max_title_length
and provide an elided title if needed. By default there is no limit to the title length.
Note
When using this setting ensure that the first sentence does not contain any special formatting you would not want in the title (bulleted lists, nested directives, etc.)
If a title is provided and the flag is present, then the provided title will be used and a warning will be issued.
.. req::
:title_from_content:
The first sentence will be the title. Anything after the first
sentence will not be part of the title.
The resulting requirement would have the title derived from the first sentence of the requirement.
The first sentence will be the title. Anything after the first sentence will not be part of the title.
0.4.1
layout
can be used to set a specific grid and content mapping.
.. req:: My layout requirement 1
:id: LAYOUT_1
:tags: layout_example
:layout: clean
Some **content** of LAYOUT_1
My layout requirement 1
Some content of LAYOUT_1
.. req:: My layout requirement 2
:id: LAYOUT_2
:tags: layout_example
:layout: complete
Some **content** of LAYOUT_2
My layout requirement 2
Some content of LAYOUT_2
.. req:: My layout requirement 3
:id: LAYOUT_3
:tags: layout_example
:layout: focus
Some **content** of LAYOUT_3
My layout requirement 3
Some content of LAYOUT_3
Please take a look into layouts
for more information.
0.4.1
style
can be used to set a specific class-attribute for the need representation.
The class-attribute can then be selected with CSS to specify the layout of the need.
Examples
My styled requirement
Another styled requirement
Green is my color
Yellow and blue border
.. req:: My styled requirement
:id: STYLE_001
:tags: style_example
:style: red
.. req:: Another styled requirement
:id: STYLE_002
:tags: style_example
:style: blue
.. req:: Green is my color
:id: STYLE_003
:tags: style_example
:style: green
.. req:: Yellow and blue border
:id: STYLE_004
:style: yellow, blue_border
By using dynamic_functions
, the value of style
can be automatically derived from the values of other need options.
Here style
is set to [[copy('status')]]
, which leads to the CSS class needs_style_open
if the status
option is set to open
.
Examples
My automatically styled requirement
My automatically styled requirement
.. req:: My automatically styled requirement
:id: STYLE_005
:status: implemented
:tags: style_example
:style: [[copy(status)]]
.. req:: My automatically styled requirement
:id: STYLE_006
:status: open
:tags: style_example
:style: [[copy(status)]]
0.5.2
By setting template
, the content of the need gets replaced by the content of the specified template.
Sphinx-Needs templates support the Jinja templating language and give access to all need data, including the original content.
The template name must be equal to the filename in the Sphinx-Needs template folder, without the file extension. For example, if the filename is my_template.need
, you can reference it like this: :template: my_template
. Sphinx-Needs templates must have the file extension .need
.
You can specify the location of all template files by configuring the needs_template_folder
, which is by default needs_templates/
, in the conf.py file.
You can have several templates, but can set only one for a need.
Template: spec_template.need
/needs_templates/spec_template.need
Need
.. spec:: My specification
:status: open
:links: FEATURE_1, FEATURE_2
:id: TEMPL_SPEC
:tags: example, template
:template: spec_template
This is my **specification** content.
My specification
This is my specification content.
You can find a list of need-value names in the documentation for filter_string
or by using the debug
layout <layouts>
.
You can automatically assign templates to specific needs by using needs_global_options
.
In Sphinx, options support multi-line content, which you can interpret like other RST input in Sphinx-Needs templates.
But there is one important constraint: Don’t use empty lines, as we use them in defining the content end. Instead, you can use __
(two underscores) to define the content end and can use |
to force line breaks.
Need :
.. req:: A really strange example
:id: multiline_1234
:status:
| First line
| Second line
| Followed by an empty line
__
A list example:
__
* take *this*
* and **this**
__
__
__
3 new lines, but 1 is shown only
__
Included directives
__
.. req:: test req
:id: abc_432
__
This works!
__
An image: wow
__
.. image:: /_images/needs_logo.png
:width: 20%
__
.. image:: /_images/needs_logo.png
:width: 30%
:template: content
Template
/needs_templates/content.need
A really strange example
0.5.4
Adds specific content from a template before a need. For example, you can use it to set a section name before each need.
Template: spec_pre_template.need
/needs_templates/spec_pre_template.need
Need
.. spec:: My specification
:id: TEMPL_PRE_SPEC
:tags: example, template
:pre_template: spec_pre_template
This is my **specification** content.
My specification
This is my specification content.
0.5.4
Adds specific content from a template after a need. You can use it to show some need-specific analytics, like dependency diagrams or table of linked needs.
Template: spec_post_template.need
/needs_templates/spec_post_template.need
Need
.. spec:: My specification
:id: TEMPL_POST_SPEC
:tags: example, template
:links: FEATURE_1, FEATURE_2
:post_template: spec_post_template
This is my **specification** content.
My specification
This is my specification content.
0.5.5
Track the duration of a need.
The need allows any value but the needgantt
directive uses and interprets it as days by default.
0.5.5
Track the completion of a need.
The need allows any value but the needgantt
directive uses and interprets it as percentage by default.
Sphinx-Needs supports the definition and filtering of customized options for needs.
You can read needs_extra_options
for detailed information and examples.
Note
To remove options from the Sphinx-Needs output in versions >= 0.5.0
, you must provide your own layout, which does not include these options. See layouts_styles
for more information.
removed: 0.5.0
Hide the status information of a need.
removed: 0.5.0
Hide the tags of a need.