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
status: open
tags: user

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!

hide_status

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

hide_tags

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

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

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

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

Customized Options

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

Please see needs_extra_options for detailed information and examples.