needextend

Added in version 0.7.0.

needextend allows to modify existing needs. It doesn’t provide any output, as the modifications get presented at the original location of the changing need, for example:

.. needextend:: <filter_string>
   :option: new value
   :+option: additional value
   :-option:

The following modifications are supported:

  • option: replaces the value of an option

  • +option: add new value to an existing value of an option.

  • -option: delete a complete option.

The argument of needextend will be taken as, by order of priority:

  • a single need ID, if it is enclosed by <>,

  • a Filter string if it is enclosed by "",

  • a single need ID, if it is a single word (no spaces),

  • a Filter string otherwise.

needextend can modify all string-based and list-based options. Also, you can add links or delete tags.

Example 1

.. req:: needextend Example 1
   :id: extend_test_001
   :status: open
   :author: Foo
   :tags: tag_1, tag_2

   This requirement got modified.

   | Status was **open**, now it is :ndf:`copy('status')`.
   | Also author got changed from **Foo** to :ndf:`copy('author')`.
   | And a tag was added.
   | Finally all links got removed.

.. req:: needextend Example 2
   :id: extend_test_002
   :tags: extend_example
   :status: open

   Contents

.. needextend:: extend_test_001
   :status: closed
   :+author: and me

.. needextend:: <extend_test_001>
   :+tags: new_tag

.. needextend:: id == "extend_test_002"
   :status: New status

.. needextend:: ""extend_example" in tags"
   :+tags: other
Requirement: needextend Example 1 extend_test_001
status: closed
tags: tag_1, tag_2, new_tag
author: Foo and me

This requirement got modified.

Status was open, now it is closed.
Also author got changed from Foo to Foo and me.
And a tag was added.
Finally all links got removed.
Requirement: needextend Example 2 extend_test_002
status: New status
tags: extend_example, other

Contents

Options

strict

The purpose of the :strict: option is to handle whether an exception gets thrown or a warning log message gets written, if there is no need object to match the needextend's required argument (e.g. an ID).

If you set the :strict: option value to true, needextend raises an exception because the given ID does not exist, and the build stops.

If you set the :strict: option value to false, needextend logs an warning-level message in the console, and the build continues.

Allowed values:

  • true or

  • false

Default: false

Note

We have a configuration (conf.py) option called needs_needextend_strict that deactivates or activates the :strict: option behaviour for all needextend directives in a project.

Extending needs in current page

Added in version 5.0.0.

The c.this_doc() function is made available, to filter for needs only in the same document as the needextend.

The following example would set the status of all needs in the current document, which do not have the status set explicitly, to open.

Example 2

.. needextend:: c.this_doc() and status is None
   :status: open

See also, Filtering for needs on the current page and needs_global_options for setting a default option value for all needs.

Monitoring modifications

All needs have this two internal parameters:

  • is_modified: A boolean value. Defaults to False

  • modifications: A number. Defaults to 0.

If a need gets changed by a needextend directive, is_modified is changed to True. Also, the modifications number is increased by one. +1 for each executed needextend on this need.

To see these values, use :layout: debug on the need or by Defining own layouts.

Also filtering for these values is supported:

Example 4

We have :need_count:`is_modified` modified needs.

.. needtable::
   :filter: "needextend" in title
   :columns: id, title, status, is_modified, modifications
   :style: table

We have 11 modified needs.

ID

Title

Status

Is Modified

Modifications

extend_test_001

needextend Example 1

closed

True

2

extend_test_002

needextend Example 2

New status

True

2

extend_test_003

needextend Example 3

open

True

2

extend_test_004

needextend Example 4

open

True

1

extend_test_005

needextend Example 5

open

True

2

extend_test_006

needextend Example 6

open

True

3