Skip to content
Back to top
View this page
Edit this page

# need items

Creates a need object with a specified type. You can define the type using the correct directive, like `.. req::` or `.. test::`.

Example 1

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

Requirement: User needs to login ID123
status: open tags: user, 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.

## Variants for options support

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

### Rules for specifying variant definitions

- 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, like `var_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.

### Use Case 1

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.

For example, in your `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.

### Use Case 2

In this example, you can use the filter string directly in the need option’s variant definition.

For example, 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.

### Use Case 3

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:

Example 2

    .. req:: Variant options
       :id: VA_004
       :status: ['variants' in tags and not collapse]:enabled, disabled
       :tags: variants;support
       :collapse:

       Variants for need options in action

Requirement: Variant options VA_004
status: disabled tags: variants, support
Variants for need options in action

## Diagram support

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.

Example 3

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

Specification: Interfaces SP_INT
status: open
This are the provided interfaces:

Reuse of Interfaces (SP_INT) inside a needuml:

This simple mechanism is really powerful to design reusable and configurable SW architecture diagrams. For more examples and details, please read needuml.

### Filter for diagrams

The option `arch` can be easily used for filtering. For instance to show all need objects, which are representing some kind of a diagram.

Example 4

    .. needtable::
       :filter: bool(arch)
       :style: table
       :columns: id, type, title

ID | Type | Title
--- | --- | ---
COMP_001 | comp | Component X
COMP_002 | comp | Component Y
COMP_A_B | comp | Variant A or B
COMP_NEEDUML2 | comp | NeedUml example need 2
COMP_T_001 | comp | COMP_T_001
COMP_T_002 | comp | COMP_T_002
COMP_T_003 | comp | COMP_T_003
COMP_X | comp | Component X
COMP_Z | comp | Z
INT_001 | int | Test needuml save
INT_A | int | Interface A
req_arch_001 | req | Requirement arch
req_arch_004 | req | Req Arch four
SP_INT | spec | Interfaces
SYS_ROCKET | sys | System RocketScience
test_arch_001 | test | Test Arch

## Options for Need Type

### id

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.

### status

A need can only have one status, and the needs_statuses configuration parameter may restrict its selection.

### tags

You can give multiple tags by separating each with ; symbol, like `tag1;tag2;tag3`. White spaces get removed.

### links

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.

Example 5

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

Requirement: Link example Target REQ_LINK_1
links incoming: R_262A1
This is the target for a link. Itself has no link set.

Requirement: Link example Source R_262A1
links outgoing: REQ_LINK_1
This sets a link to id `REQ_LINK_1`.

#### extra links

By using 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"
       }
    ]

Example 6

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

Requirement: test me test_req
links incoming: test_001 is tested by: test_001
A requirement, which needs to be tested

Test Case: test a requirement test_001
links outgoing: test_req tests: test_req
Perform some tests

### delete

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` or `yes` or `1`

- `false` or `no` or `0`

Default: False

Note

If you delete a need using the :delete: option, the need will not be part of any filter result.

Example 7

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

Requirement: Second Requirement Need DELID123
child needs: DELID124

Need with `:delete:` equal to `false`.

Specification: Nested Need without delete option DELID124
tags: nested-del-need parent needs: DELID123
Need with `:delete:` option not set.

### hide

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.

### collapse

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

Example 8

    .. req:: Collapse is set to True
       :tags: collapse; example
       :collapse:

       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.

Requirement: Collapse is set to True R_A2D07
tags: collapse, example
Only title and content are shown

Requirement: Collapse is set to False R_316DE
tags: collapse, example
Title, tags, links and everything else is shown directly.

### jinja_content

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:

- empty, `true` or `yes`

- `false` or `no`

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'
    }

Example 9

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

          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:

       Need with ``:jinja_content:`` equal to ``true``.
       This requirement has status: **{{ status }}**.

Requirement: First Req Need JINJAID123
child needs: JINJAID125

Need with `:jinja_content:` equal to `false`.

Specification: Nested Spec Need JINJAID125
status: open tags: user, login links outgoing: JINJAID126 parent needs: JINJAID123

Nested need with `:jinja_content:` option set to `true`. This requirement has tags: user, login.

It links to:

- JINJAID126

Specification: First Spec Need JINJAID126
status: open links incoming: JINJAID125
Need with `:jinja_content:` equal to `true`. This requirement has status: open.

### title_from_content

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

Example 10

    .. req::
       :title_from_content:

       The first sentence will be the title.
       Anything after the first sentence will not be part of the title.

Requirement: The first sentence will be the title R_BAFCF
The first sentence will be the title. Anything after the first sentence will not be part of the title.

### layout

Added in version 0.4.1.

`layout` can be used to set a specific grid and content mapping.

Example 11

    .. req:: My layout requirement 1
       :id: LAYOUT_1
       :tags: layout_example
       :layout: clean

       Some **content** of LAYOUT_1

Requirement: My layout requirement 1 LAYOUT_1
tags: layout_example layout: clean
Some content of LAYOUT_1

Example 12

    .. req:: My layout requirement 2
       :id: LAYOUT_2
       :tags: layout_example
       :layout: complete

       Some **content** of LAYOUT_2

LAYOUT_2 | My layout requirement 2 | Requirement
tags: layout_example |
Some content of LAYOUT_2

Example 13

    .. req:: My layout requirement 3
       :id: LAYOUT_3
       :tags: layout_example
       :layout: focus

       Some **content** of LAYOUT_3

Some content of LAYOUT_3

Please take a look into Layouts for more information.

### style

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

Example 14

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

Requirement: My styled requirement STYLE_001
tags: style_example style: red links incoming: TEMPL_SPEC, TEMPL_POST_SPEC

Requirement: Another styled requirement STYLE_002
tags: style_example style: blue links incoming: TEMPL_SPEC, TEMPL_POST_SPEC

Requirement: Green is my color STYLE_003
tags: style_example style: green

Requirement: Yellow and blue border 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`.

Example 15

    .. 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")]]

Requirement: My automatically styled requirement STYLE_005
status: implemented tags: style_example style: implemented

Requirement: My automatically styled requirement STYLE_006
status: open tags: style_example style: open

### template

Added in version 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`

    {# Comment, no output here #}
    A line before the content

    {# Place the original content here #}
    {{content}}

    {# Use {{..}} to access need values #}
    Status: **{{status}}**

    Template: **{{template}}.need**

    {# You can also loop over need values #}
    Tags:
    {% for tag in tags %}
    {{loop.index}}. tag: **{{tag}}**
    {% endfor %}

    {# Access to values from other needs can be done #}
    {# by using dynamic_functions #}
    Links:
    {% for link in links %}
    | **{{link}}**: :ndf:`copy('title', '{{link}}')` (:ndf:`copy('type_name', '{{link}}')`)
    {%- endfor %}

Example 16

    .. spec:: My specification
       :status: open
       :links: STYLE_001, STYLE_002
       :id: TEMPL_SPEC
       :tags: example, template
       :template: spec_template

       This is my **specification** content.

Specification: My specification TEMPL_SPEC
status: open tags: example, template links outgoing: STYLE_001, STYLE_002

A line before the content

This is my specification content.

Status: open

Template: spec_template.need

Tags:

1. tag: example

2. tag: template

Links:

STYLE_001: My styled requirement (Requirement)
STYLE_002: Another styled requirement (Requirement)

You can find a list of need-value names in the documentation for Filter string or by using the `debug` layout.

You can automatically assign templates to specific needs by using needs_global_options.

### pre_template

Added in version 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`

    **{{title}}**

    Ohh nice we got a bold written "title" before our need.

Example 17

    .. spec:: My specification
       :id: TEMPL_PRE_SPEC
       :tags: example, template
       :pre_template: spec_pre_template

       This is my **specification** content.

My specification

Ohh nice we got a bold written “title” before our need.

Specification: My specification TEMPL_PRE_SPEC
tags: example, template
This is my specification content.

### post_template

Added in version 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`

    **Analytics for above need:** {{title}}

    .. needflow::
       :filter: id == '{{id}}' or '{{id}}' in links_back

Example 18

    .. spec:: My specification
       :id: TEMPL_POST_SPEC
       :tags: example, template
       :links: STYLE_001, STYLE_002
       :post_template: spec_post_template

       This is my **specification** content.

Specification: My specification TEMPL_POST_SPEC
tags: example, template links outgoing: STYLE_001, STYLE_002
This is my specification content.

Analytics for above need: My specification

### duration

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

### completion

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

## Customized Options

Sphinx-Needs supports the definition and filtering of customized options for needs.

You can read needs_extra_options for detailed information and examples.