need/ req (or any other defined need type)

Creates a need with specified type. The type is defined by 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**.
Requirement: User needs to login ID123 ../_images/arrow-right-circle.svg
status: open
tags: user, login
Our users needs to get logged in via our login forms on /login.php.

This creates a new requirement, with a title, content, given id, a status and several tags.

All options are optional, only the title as argument must be given (if needs_title_from_content is not set).

Note

By default the above example works also with .. spec::, .. impl::, .. test:: and all other need types, which are configured via needs_types.

Options

Supported options:

id

The given ID must match the regular expression of config parameter needs_id_regex. If it does not match, the build stops.

If no id is given, a short hash value is calculated based on the title. If the title gets not changed, the id will be stable for all upcoming documentation generations.

status

A need can only have one status and its selection may be restricted by config parameter needs_statuses.

tags

Tags must be separated by “;”, like tag1; tag2;tag3. Whitespaces get removed.

hide

There is an option :hide:, if this is set (no value is needed), the need will not be printed in documentation. But it will show up in need filters!

collapse

If set to True, details like status, links or tags are collapsed and viewable only after a click on the need title.

If set to False, details are shown directly.

If not set, the config parameter needs_collapse_details decides about the behavior.

Allowed values:

  • true; yes; 1
  • false; no; 0
.. 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.
Requirement: Collapse is set to True R_A2D07 ../_images/arrow-right-circle.svg
tags: collapse, example
Only title and content are shown
Requirement: Collapse is set to False R_316DE ../_images/arrow-right-circle.svg
tags: collapse, example
Title, tags, links and everything else is shown directly.

title_from_content

New in version 0.2.3.

When this flag is provided on an individual need, a title will be derived from the first sentence of the content. If not title and no content is provided then the build process will fail.

The derived title will respect the needs_max_title_length and provide an ellided title if needed. By default there is no limit to the title length.

When using this setting be sure to exercise caution that special formatting that you would not want in the title (bulleted lists, nested directives, etc.) do not appear in the first sentence.

If a title is provided and the flag is present, then the provided title will be used and a warning will be issued.

Example:

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

Requirement: The first sentence will be the title R_BAFCF ../_images/arrow-right-circle.svg
The first sentence will be the title. Anything after the first sentence will not be part of the title.

layout

New in version 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
Requirement: My layout requirement 1 LAYOUT_1 ../_images/arrow-right-circle.svg
tags: layout_example
layout: clean
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
Requirement
tags: layout_example
Some content of LAYOUT_2
.. 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

New 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 addressed by css to specify the layout of the need.

Requirement: My styled requirement STYLE_001 ../_images/arrow-right-circle.svg
tags: style_example
style: red
 
Requirement: Another styled requirement STYLE_002 ../_images/arrow-right-circle.svg
tags: style_example
style: blue
 
Requirement: Green is my color STYLE_003 ../_images/arrow-right-circle.svg
tags: style_example
style: green
 
Requirement: Yellow and blue border STYLE_004 ../_images/arrow-right-circle.svg
style: yellow, 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 combined with values from other need options.

Here style is set to [[copy('status')]], which leads to the css class needs_style_open if style is set to open.

Requirement: My automatically styled requirement STYLE_005 ../_images/arrow-right-circle.svg
status: implemented
tags: style_example
style: implemented
 
Requirement: My automatically styled requirement STYLE_006 ../_images/arrow-right-circle.svg
status: open
tags: style_example
style: open
 
.. 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)]]

template

New 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 template language Jinja and gives access to all need data, including the original content.

The template name must be the same as a file name in the Sphinx-Needs template folder, without the file extension. So a file named my_template.need must be referenced like this: :template: my_template. Sphinx-Needs templates must always use the file extension .need.

The location of all template files is specified by needs_template_folder, which is by default needs_templates/.

There can be several templates in parallel, but only one can be set for a need.

Example

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}}**: [[copy('title', '{{link}}')]] ([[copy('type_name', '{{link}}')]])
{%- endfor %}

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.

Result

Specification: My specification TEMPL_SPEC ../_images/arrow-right-circle.svg
status: open
tags: example, template
template: spec_template
links outgoing: FEATURE_1, FEATURE_2

A line before the content

This is my specification content.

Status: open

Template: spec_template.need

Tags:

  1. tag: example
  2. tag: template

Links:

FEATURE_1: Filtering needs (Feature)
FEATURE_2: Ex/Importing needs (Feature)

A list of available need-value names can be found in the documentation of Filter string or by using the debug layout.

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

pre_template

New in version 0.5.4.

Adds specific content before the whole need. This may be useful to e.g. set a section name before each need.

Example

Template: spec_pre_template.need

**{{title}}**

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

Need

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

   This is my **specification** content.

Result

My specification

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

Specification: My specification TEMPL_PRE_SPEC ../_images/arrow-right-circle.svg
tags: example, template
pre_template: spec_pre_template
This is my specification content.

post_template

New in version 0.5.4.

Adds specific content after the whole need. This may be useful to show some need-specific analytics, like dependency diagrams or table of linked needs.

Example

Template: spec_post_template.need

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

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

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.

Result

Specification: My specification TEMPL_POST_SPEC ../_images/arrow-right-circle.svg
tags: example, template
post_template: spec_post_template
links outgoing: FEATURE_1, FEATURE_2
This is my specification content.

Analytics for above need: My specification

@startuml

' Nodes definition 

node "<size:12>Specification</size>\n**My**\n**specification**\n<size:10>TEMPL_POST_SPEC</size>" as TEMPL_POST_SPEC [[../directives/need.html#TEMPL_POST_SPEC]] #FEDCD2 
node "<size:12>Feature</size>\n**Filtering needs**\n<size:10>FEATURE_1</size>" as FEATURE_1 [[../index.html#FEATURE_1]] #FFCC00 
node "<size:12>Feature</size>\n**Ex/Importing**\n**needs**\n<size:10>FEATURE_2</size>" as FEATURE_2 [[../index.html#FEATURE_2]] #FFCC00 

' Connection definition 

TEMPL_POST_SPEC --> FEATURE_1
TEMPL_POST_SPEC --> FEATURE_2

@enduml

Customized Options

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

Please see needs_extra_options for detailed information and examples.

Removed Options

hide_status

removed: 0.5.0

Note

To remove options from output in Sphinx-Needs version >= 0.5.0 you must provide your own layout, which does not include these options. See Layouts & Styles for more information.

You can also use :hide_status: to hide status information for a need.

hide_tags

removed: 0.5.0

Note

To remove options from output in Sphinx-Needs version >= 0.5.0 you must provide your own layout, which does not include these options. See Layouts & Styles for more information.

Or use :hide_tags: to hide the tags of a need.