Configuration

All root configurations take place in your project’s conf.py file.

Activation

Add sphinx_needs to your extensions.

extensions = ["sphinx_needs",]

Available sphinx-needs options are then listed below, that can be added to your conf.py file.

Added in version 4.1.0: Configuration can also be specified via a toml file. See needs_from_toml for more details.

Build Warnings

sphinx-needs is designed to be durable and only except when absolutely necessary. Any non-fatal issues during the build are logged as Sphinx warnings.

If you wish to “fail-fast” during a build, see the –fail-on-warning command-line option (in sphinx 8.1 --exception-on-warning).

You can also use this in conjunction with the suppress_warnings configuration option, to suppress specific warnings.

Find below a list of all warnings, which can be suppressed:

  • needs.config Invalid configuration

  • needs.constraint Constraint violation

  • needs.create_need Creation of a need from directive failed

  • needs.delete_need Deletion of a need failed

  • needs.deprecated Deprecated feature

  • needs.diagram_scale Failed to process diagram scale option

  • needs.duplicate_id Duplicate need ID found when merging needs from parallel processes

  • needs.duplicate_part_id Duplicate part ID found when parsing need content

  • needs.dynamic_function Failed to load/execute dynamic function

  • needs.external_link_outgoing Unknown outgoing link in external need

  • needs.needextend Error processing needextend directive

  • needs.needextract Error processing needextract directive

  • needs.needflow Error processing needflow directive

  • needs.needgantt Error processing needgantt directive

  • needs.needimport Error processing needimport directive

  • needs.needreport Error processing needreport directive

  • needs.needsequence Error processing needsequence directive

  • needs.filter Error processing needs filter

  • needs.filter_func Error loading needs filter function

  • needs.github Error in processing GitHub service directive

  • needs.import_need Failed to import a need

  • needs.json_load

  • needs.layout Error occurred during layout rendering of a need

  • needs.link_outgoing Unknown outgoing link in standard need

  • needs.link_ref Need could not be referenced

  • needs.link_text Reference text could not be generated

  • needs.load_external_need Failed to load an external need

  • needs.load_service_need Failed to load a service need

  • needs.mpl Matplotlib required but not installed

  • needs.title Error creating need title

  • needs.uml Error in processing of UML diagram

  • needs.unknown_external_keys Unknown keys found in external need data

  • needs.mistyped_external_values Unexpected value types found in external need data

  • needs.unknown_import_keys Unknown keys found in imported need data

  • needs.mistyped_import_values Unexpected value types found in imported need data

  • needs.variant Error processing variant in need field

  • needs.warnings Need warning check failed for one or more needs

Incremental build support

Sphinx does not use its incremental build feature, if you assign functions directly to Sphinx options. To avoid this, please use the Sphinx-Needs API to register functions directly.

This would allow Sphinx to perform incremental builds which are much faster as compared to full builds.

Example configuration

# conf.py

# Defining one or more functions in conf.py is fine
def my_custom_warning(need, log):
    # some checks
    return False

def my_dynamic_function(app, need, needs):
    return "some text"

# This assignment will deactivate incremental build support inside Sphinx
needs_warnings = {
   'my_warning_no_inc_build': my_custom_warning
}

# Better, register the function via Sphinx-Needs API
from sphinx_needs.api.configuration import add_warning, add_dynamic_function
def setup(app):
   add_warning(app, 'my_warning', my_custom_warning)
   add_dynamic_function(app, my_dynamic_function)

Hint

You are free to use e.g. needs_warnings and add_warning() together in a conf.py file. Sphinx-Needs creates internally a final list of elements defined by config-var and api-call.

However, you should not use the same id in a config-var and the related api-call, as this would create the related element twice.

Options

All configuration options starts with the prefix needs_ for Sphinx-Needs.

needs_from_toml

Added in version 4.1.0.

This configuration takes the (relative) path to a toml file which contains some or all of the needs configuration (configuration in the toml will override that in the conf.py).

needs_from_toml = "ubproject.toml"

Configuration in the toml can contain any of the options below, under a [needs] section, but with the needs_ prefix removed. For example:

[needs]
id_required = true
id_length = 3
types = [
   {directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"},
   {directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"},
]

To specify a different root table path to read from in the toml file, use the needs_from_toml_table option. For example to read from a [tool.needs] table:

needs_from_toml_table = ["tool"]

Caution

Any configuration specifying relative paths in the toml file will be resolved relative to the directory containing the conf.py file.

needs_include_needs

Set this option to False, if no needs should be documented inside the generated documentation.

Default: True

needs_include_needs = False

needs_id_length

This option defines the length of an automated generated ID (the length of the prefix does not count).

Default: 5

needs_id_length = 3

needs_types

The option allows the setup of own need types like bugs, user_stories and more.

By default it is set to:

needs_types = [dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"),
               dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"),
               dict(directive="impl", title="Implementation", prefix="I_", color="#DF744A", style="node"),
               dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node"),
               # Kept for backwards compatibility
               dict(directive="need", title="Need", prefix="N_", color="#9856a5", style="node")
           ]

needs_types must be a list of dictionaries where each dictionary must contain the following items:

  • directive: Name of the directive. For instance, you can use “req” via .. req:: in documents

  • title: Title, used as human readable name in lists

  • prefix: A prefix for generated IDs, to easily identify that an ID belongs to a specific type. Can also be “”

  • color: A color as hex value. Used in diagrams and some days maybe in other representations as well. Can also be “”

  • style: A plantuml node type, like node, artifact, frame, storage or database. See plantuml documentation for more.

Note

color can also be an empty string. This makes sense, if the PlantUMl configuration is mostly provided by using needs_flow_configs and the used colors shall not get overwritten by type specific values.

Warning

If a need type shall contain need_part / np and later be printed via needflow, the chosen PlantUML node type must support nested elements for this type.

Types who support nested elements are for instance: node, package, frame. Not supporting elements are for instance usecase, actor.

Please take a look into the PlantUML Manual for more details.

needs_extra_options

Added in version 0.2.2.

The option allows the addition of extra options that you can specify on needs.

You can set needs_extra_options as a list inside conf.py as follows:

needs_extra_options = ['introduced', 'updated', 'impacts']

And use it like:

.. req:: My Requirement
   :status: open
   :introduced: Yes
   :updated: 2018/03/26
   :tags: important;complex;
   :impacts: really everything

Note

To filter on these options in needlist, needtable, etc. you must use the Filtering needs option.

Show example

conf.py

needs_extra_options = ["my_extra_option",  "another_option"]

index.rst

.. req:: My requirement with custom options
   :id: xyz_123
   :status: open
   :my_extra_option: A new option
   :another_option: filter_me

   Some content

.. needlist::
   :filter: "filter_me" in another_option

Result

Requirement: My requirement with custom options xyz_123
status: open
my_extra_option: A new option
another_option: filter_me

Some content

Added in version 4.1.0: Values in the list can also be dictionaries, with keys:

  • name: The name of the option (required).

  • description: A description of the option (optional).

    This will be output in the schema of the needs.json, and can be used by other tools.

For example:

needs_extra_options = [
    "my_extra_option",
    {"name": "my_other_option", "description": "This is a description of the option"}
]

needs_global_options

Added in version 0.3.0.

Changed in version 5.1.0: The format of the global options was change to be more explicit.

Unknown keys are also no longer accepted, these should also be set in the needs_extra_options list.

Comparison to old format
Old format
needs_global_options = {
    "field1": "a",
    "field2": ("a", 'status == "done"'),
    "field3": ("a", 'status == "done"', "b"),
    "field4": [
        ("a", 'status == "done"'),
        ("b", 'status == "ongoing"'),
        ("c", 'status == "other"', "d"),
    ],
}
New format
needs_global_options = {
    "field1": {"default": "a"},
    "field2": {"predicates": [('status == "done"', "a")]},
    "field3": {
        "predicates": [('status == "done"', "a")],
        "default": "b",
    },
    "field4": {
        "predicates": [
            ('status == "done"', "a"),
            ('status == "ongoing"', "b"),
            ('status == "other"', "c"),
        ],
        "default": "d",
    },
}

This configuration allows for global defaults to be set for all needs, for any of the following fields:

  • any needs_extra_options field

  • any needs_extra_links field

  • status

  • layout

  • style

  • tags

  • constraints

Defaults will be used if the field is not set specifically by the user and thus has a “empty” value.

needs_extra_options = ["option1"]
needs_global_options = {
   "tags": {"default": ["tag1", "tag2"]},
   "option1": {"default": "new value"},
}

To set a default based on a one or more predicates, use the predicates key. These predicates are a list of (filter string, value), evaluated in order, with the first match set as the default value. If no predicates match, the default value is used (if present).

needs_extra_options = ["option1"]
needs_global_options = {
   "option1": {
   # if field is unset:
      "predicates": [
         # if status is "done", set to "value1"
         ("status == 'done'", "value1"),
         # else if status is "ongoing", set to "value2"
         ("status == 'ongoing'", "value2"),
      ]
      # else, set to "value3"
      "default": "value3",
   }
}

Tip

You can combine global options with Dynamic functions to automate data handling.

needs_extra_options = ["option1"]
needs_global_options = {
        "option1": {"default": '[[copy("id")]]'}
}

Warning

The filter string gets executed against the current need only and has no access to other needs. So avoid any references to other needs in the filter string.

If you need access to other needs for complex filtering, you can maybe provide your own Dynamic functions and perform the filtering there.

Default replacements are done, for each field, in the order they are defined in the configuration, so a filter string should not depend on the value of a field below it in the configuration.

needs_filter_data

This option allows to use custom data inside a Filter string.

Configuration example:

def custom_defined_func():
    return "my_tag"

needs_filter_data = {
    "current_variant": "project_x",
    "sphinx_tag": custom_defined_func(),
}

The defined needs_filter_data must be a dictionary. Its values can be a string variable or a custom defined function. The function get executed during config loading and must return a string.

The value of needs_filter_data will be available as data inside Filter string and can be very powerful together with internal needs information to filter needs.

The defined extra filter data can be used like this:

.. needextend:: type == "req" and sphinx_tag in tags
   :+tags: my_external_tag

or if project has needs_extra_options defined like:

needs_extra_options = ['variant']

The defined extra filter data can also be used like:

.. needlist::
   :filter: variant != current_variant

.. needextract::
   :filter: type == "story" and variant == current_variant
   :layout: clean
   :style: green_border

needs_allow_unsafe_filters

Allow unsafe filter for Filter function. Default is False.

If set to True, the filtered results will keep all fields as they are returned by the dynamic functions. Fields can be added or existing fields can even be manipulated.

Note

Keep in mind this only affects the filter results, original needs as displayed somewhere else are not modified.

If set to False, the filter results contains the original need fields and any manipulations of need fields are lost.

needs_allow_unsafe_filters = True

needs_filter_max_time

Added in version 4.0.0.

If set, warn if any filter processing call takes longer than the given time in seconds.

needs_uml_process_max_time

Added in version 4.0.0.

If set, warn if any needuml or needarch jinja content rendering takes longer than the given time in seconds.

needs_flow_engine

Added in version 2.2.0.

Select between the rendering engines for needflow diagrams,

  • plantuml: Use PlantUML to render the diagrams (default).

  • graphviz: Use Graphviz to render the diagrams.

needs_flow_configs

Added in version 0.5.2.

needs_flow_configs must be a dictionary which can store multiple PlantUML configurations. These configs can then be selected when using needflow.

needs_flow_configs = {
   'my_config': """
       skinparam monochrome true
       skinparam componentStyle uml2
   """,
   'another_config': """
       skinparam class {
           BackgroundColor PaleGreen
           ArrowColor SeaGreen
           BorderColor SpringGreen
       }
   """
}

This configurations can then be used like this:

Example 2

.. needflow::
    :tags: flow_example
    :types: spec
    :config: lefttoright,my_config

@startuml

' Config

left to right direction
skinparam monochrome true
skinparam componentStyle uml2


' Nodes definition 

node "<size:12>Specification</size>\n**A specification**\n<size:10>spec_flow_001</size>" as spec_flow_001 [[../directives/needflow.html#spec_flow_001]] #FEDCD2{
'parts:
rectangle "<size:12>Specification (part)</size>\n**A testable part**\n**of the**\n**specification**\n<size:10>spec_flow_001.**subspec_1**</size>" as spec_flow_001.subspec_1 [[../directives/needflow.html#spec_flow_001.subspec_1]] #FEDCD2
rectangle "<size:12>Specification (part)</size>\n**Another**\n**testable part**\n**of the**\n**specification**\n<size:10>spec_flow_001.**subspec_2**</size>" as spec_flow_001.subspec_2 [[../directives/needflow.html#spec_flow_001.subspec_2]] #FEDCD2
'child needs:
node "<size:12>Specification</size>\n**A child**\n**specification**\n<size:10>spec_flow_003</size>" as spec_flow_003 [[../directives/needflow.html#spec_flow_003]] #FEDCD2
}
node "<size:12>Specification</size>\n**Another**\n**specification**\n<size:10>spec_flow_002</size>" as spec_flow_002 [[../directives/needflow.html#spec_flow_002]] #FEDCD2

' Connection definition 

spec_flow_002 --> spec_flow_001
spec_flow_002 -[#AA0000]-o spec_flow_001

@enduml

Multiple configurations can be used by separating them with a comma, these will be applied in the order they are defined.

See needflow config option for more details and already available configurations.

needs_graphviz_styles

Added in version 2.2.0.

This must be a dictionary which can store multiple Graphviz configurations. These configs can then be selected when using needflow and the engine is set to graphviz.

needs_graphviz_styles = {
    "my_config": {
        "graph": {
            "rankdir": "LR",
            "bgcolor": "transparent",
        },
        "node": {
            "fontname": "sans-serif",
            "fontsize": 12,
        },
        "edge": {
            "color": "#57ACDC",
            "fontsize": 10,
        },
    }
}

This configurations can then be used like this:

.. needflow::
    :engine: graphviz
    :config: lefttoright,my_config

Multiple configurations can be used by separating them with a comma, these will be merged in the order they are defined. For example my_config1,my_config2 would be the same as my_config3:

needs_graphviz_styles = {
    "my_config1": {
        "graph": {
            "rankdir": "LR",
        }
    },
    "my_config2": {
        "graph": {
            "bgcolor": "transparent",
        }
    }
    "my_config3": {
        "graph": {
            "rankdir": "LR",
            "bgcolor": "transparent",
        }
    }
}

needs_report_template

Added in version 1.0.1.

You can customize the layout of needreport using Jinja.

Set the value of needs_report_template to the path of the template you want to use.

Note

The path must be an absolute path based on the conf.py directory. Example: needs_report_template = '/needs_templates/report_template.need'

The template file should be a plain file with any of the following file extensions: .rst, .need, or .txt.

If you do not set needs_report_template, the default template used is:

{# Output for needs_types #}
{% if types|length != 0 %}
.. dropdown:: Need Types
   :class: needs_report_table

   .. list-table::
     :widths: 40 20 20 20
     :header-rows: 1

     * - TITLE
       - DIRECTIVE
       - PREFIX
       - STYLE
     {% for type in types %}
     * - {{ type.title }}
       - {{ type.directive }}
       - `{{ type.prefix }}`
       - {{ type.style }}
     {% endfor %}
{% endif %}
{# Output for needs_types #}

{# Output for needs_extra_links #}
{% if links|length != 0 %}
.. dropdown:: Need Extra Links
   :class: needs_report_table

   .. list-table::
     :widths: 10 30 30 5 20
     :header-rows: 1

     * - OPTION
       - INCOMING
       - OUTGOING
       - COPY
       - ALLOW DEAD LINKS
     {% for link in links %}
     * - {{ link.option | capitalize }}
       - {{ link.incoming | capitalize }}
       - {{ link.outgoing | capitalize }}
       - {{ link.get('copy', None) | capitalize }}
       - {{ link.get('allow_dead_links', False) | capitalize }}
     {% endfor %}
{% endif %}
{# Output for needs_extra_links #}

{# Output for needs_options #}
{% if options|length != 0 %}
.. dropdown:: Need Extra Options
   :class: needs_report_table

   {% for option in options %}
   * {{ option }}
   {% endfor %}
{% endif %}
{# Output for needs_options #}

{# Output for needs metrics #}
{% if usage|length != 0 %}
.. dropdown:: Need Metrics

   .. list-table::
      :widths: 40 40
      :header-rows: 1

      * - NEEDS TYPES
        - NEEDS PER TYPE
      {% for k, v in usage["needs_types"].items() %}
      * - {{ k | capitalize }}
        - {{ v }}
      {% endfor %}
      * - **Total Needs Amount**
        - {{ usage.get("needs_amount") }}
{% endif %}
{# Output for needs metrics #}

The plugin provides the following variables which you can use in your custom Jinja template:

  • types - list of need types

  • links - list of extra need links

  • options - list of extra need options

  • usage - a dictionary object containing information about the following:
    • needs_amount -> total amount of need objects in the project

    • needs_types -> number of need objects per needs type

needs_diagram_template

This option allows to control the content of diagram elements which get automatically generated by using .. needflow:: / needflow (when using the plantuml engine).

This function is based on plantuml, so that each supported style can be used.

The rendered template is used inside the following plantuml syntax and must care about leaving the final string valid:

'node "YOUR_TEMPLATE" as need_id [[need_link]]'

By default the following template is used:

{%- if is_need -%}
<size:12>{{type_name}}</size>\\n**{{title|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id}}</size>
{%- else -%}
<size:12>{{type_name}} (part)</size>\\n**{{content|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id_parent}}.**{{id}}**</size>
{%- endif -%}

needs_id_required

Added in version 0.1.19.

Forces the user to set an ID for each need, which gets defined.

So no ID is autogenerated any more, if this option is set to True:

needs_id_required = True

By default this option is set to False.

Example:

.. With needs_id_required = True

.. req:: Working Requirement
   :id: R_001

.. req:: **Not working**, because :id: is not set.


.. With needs_id_required = False

.. req:: This works now!

needs_id_from_title

Generates needs ID from title. By default, this setting is set to False.

When no need ID is given by the user, and needs_id_from_title is set to True, then a need ID will be calculated based on the current need directive prefix, title, and a hashed value from title.

Example 3

.. req:: Group big short
Requirement: Group big short R_446C7

The calculated need ID will be: R_GROUP_BIG_SHORT_{hashed value}, if the need ID length doesn’t exceed the setting from needs_id_length.

Note

The user needs to ensure the uniqueness of the given title, and also match the settings of needs_id_length and needs_id_regex.

needs_title_optional

Added in version 0.2.3.

Normally a title is required to follow the need directive as follows:

.. req:: This is the required title
    :id: R_9999

By default this option is set to False.

When this option is set to True, a title does not need to be provided, but either some content or an :id: element will be required. If a title is not provided and no ID is provided, then an ID will be generated based on the content of the requirement.

It is important to note in these scenarios that titles will not be available in other directives such as needtable, needlist, needflow.

A title can be auto-generated for a requirement by either setting needs_title_from_content to True or providing the flag :title_from_content: as follows:

The resulting requirement would have the title derived from the first sentence of the requirement.

Example 4

.. req::
    :title_from_content:

    This will be my title.  Anything after the first sentence will not be
    part of the title.
Requirement: This will be my title R_D8F29

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

needs_title_from_content

Added in version 0.2.3.

This setting defaults to False. When set to True and a need does not provide a title, then a title will be generated using the first sentence in the content of the requirement. The length of the title will adhere to the needs_max_title_length setting (which is not limited by default).

Note

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 specified for an individual requirement, then that title will be used over the generated title.

Example 5

.. req::

    The tool must have error logging.
    All critical errors must be written to the console.
Requirement: R_3FFAA

The tool must have error logging. All critical errors must be written to the console.

needs_max_title_length

This option is used in conjunction with auto-generated titles as controlled by needs_title_from_content and title_from_content. By default, there is no limit to the length of a title.

If you provide a maximum length and the generated title exceeds that limit, then we use an elided version of the title.

When generating a requirement ID from the title, the full generated title will still be used.

Example:

Requirement: This is a requirement with a very long title that will need to be R_565A6

This is a requirement with a very long title that will need to be shortened to prevent our titles from being too long. Additional content can be provided in the requirement and not be part of the title.

needs_file

Added in version 0.1.30.

Defines the location of a JSON file, which is used by the builder needs as input source. Default value: needs.json.

needs_statuses

Added in version 0.1.41.

Defines a set of valid statuses, which are allowed to be used inside documentation. If we detect a status not defined, an error is thrown and the build stops. The checks are case sensitive.

Activate it by setting it like this:

needs_statuses = [
    dict(name="open", description="Nothing done yet"),
    dict(name="in progress", description="Someone is working on it"),
    dict(name="implemented", description="Work is done and implemented"),
]

If parameter is not set or set to False, no checks will be performed.

Default value: [].

needs_tags

Added in version 0.1.41.

Defines a set of valid tags, which are allowed to be used inside documentation. If we detect a tag not defined, an error is thrown and the build stops. The checks are case sensitive.

Activate it by setting it like this:

needs_tags = [
    dict(name="new", description="new needs"),
    dict(name="security", description="tag for security needs"),
]

If parameter is not set or set to [], no checks will be performed.

Default value: [].

needs_css

Added in version 0.1.42.

Defines the location of a CSS file, which will be added during documentation build.

If path is relative, Sphinx-Needs will search for related file in its own CSS-folder only! Currently supported CSS files:

  • blank.css : CSS file with empty styles

  • modern.css: modern styles for a need (default)

  • dark.css: styles for dark page backgrounds

Use it like this:

needs_css = "blank.css"

To provide your own CSS file, the path must be absolute. Example:

import os

conf_py_folder = os.path.dirname(__file__)
needs_css =  os.path.join(conf_py_folder, "my_styles.css")

See Sphinx-needs CSS option for available CSS selectors and more.

needs_role_need_template

Added in version 0.1.48.

Provides a way of changing the text representation of a referenced need.

If you use the role need, Sphinx-Needs will create a text representation of the referenced need. By default a referenced need is described by the following string:

{title} ({id})

By using needs_role_need_template this representation can be easily adjusted to own requirements.

Here are some ideas, how it could be used inside the conf.py file:

needs_role_need_template = "[{id}]: {title}"
needs_role_need_template = "-{id}-"
needs_role_need_template = "{type}: {title} ({status})"
needs_role_need_template = "{title} ({tags})"
needs_role_need_template = "{title:*^20s} - {content:.30}"
needs_role_need_template = "[{id}] {title} ({status}) {type_name}/{type} - {tags} - {links} - {links_back} - {content}"

needs_role_need_template must be a string, which supports the following placeholders:

  • id

  • type (short version)

  • type_name (long, human readable version)

  • title

  • status

  • tags, joined by “;”

  • links, joined by “;”

  • links_back, joined by “;”

  • content

All options of Python’s .format() function are supported. Please see https://pyformat.info/ for more information.

RST-attributes like **bold** are not supported.

needs_role_need_max_title_length

Added in version 0.3.14.

Defines the maximum length of need title that is shown in need references.

By default, need titles that are longer than 30 characters are shortened when shown in need text representation and “…” is added at end. By using needs_role_need_max_title_length, it is possible to change this maximum length.

If set to -1 the title will never be shortened.

# conf.py
needs_role_need_max_title_length = 45

needs_table_style

Added in version 0.2.0.

Defines the default style for each table. Can be overridden for specific tables by setting parameter style of directive needtable.

# conf.py
needs_table_style = "datatables"

Default value: "datatables"

Supported values:

  • table: Default Sphinx table

  • datatables: Table with activated DataTables functions (Sort, search, export, …).

needs_table_columns

Added in version 0.2.0.

Defines the default columns for each table. Can be overridden for specific tables by setting parameter columns of directive needtable.

# conf.py
needs_table_columns = "title;status;tags"

Default value: "id;title;status;type;outgoing;tags"

Supported values:

  • id

  • title

  • status

  • type

  • tags

  • incoming

  • outgoing

needs_id_regex

Added in version 0.2.0.

Defines a regular expression used to validate all manually set IDs and to generate valid IDs for needs without a given ID.

Default value: ^[A-Z0-9_]{5,}

By default, an ID is allowed to contain upper characters, numbers and underscore only. The ID length must be at least 3 characters.

Warning

An automatically generated ID of needs without a manually given ID must match the default value of needs_id_regex only.

If you change the regular expression, you should also set needs_id_required so that authors are forced to set an valid ID.

needs_functions

Added in version 0.3.0.

Used to register own dynamic functions.

Must be a list of DynamicFunction.

Default value: []

Inside your conf.py file use it like this:

needs_functions == [my_own_function]

def my_own_function(app, need, needs):
    return "Awesome"

See Dynamic functions for more information.

Warning

Assigning a function to a Sphinx option will deactivate the incremental build feature of Sphinx. Please use the Sphinx-Needs API and read Incremental build support for details.

It is better to use the following way in your conf.py file:

from sphinx_needs.api import add_dynamic_function

   def my_function(app, need, needs, *args, **kwargs):
       # Do magic here
       return "some data"

   def setup(app):
         add_dynamic_function(app, my_function)

needs_part_prefix

Added in version 0.3.6.

String used as prefix for need_part / np output in tables.

Default value: u'\u2192\u00a0'

The default value contains an arrow right and a non breaking space.

needs_part_prefix = u'\u2192\u00a0'

See show_parts for an example output.

needs_warnings

Added in version 0.5.0.

needs_warnings allows the definition of warnings which all needs must avoid during a Sphinx build.

A raised warning will print a sphinx-warning during build time.

Use -W in your Sphinx build command to stop the whole build, if a warning is raised. This will handle all warnings as exceptions.

def my_custom_warning_check(need, log):
    if need["status"] == "open":
        log.info(f"{need['id']} status must not be 'open'.")
        return True
    return False


needs_warnings = {
  # req need must not have an empty status field
  'req_with_no_status': "type == 'req' and not status",

  # status must be open or closed
  'invalid_status' : "status not in ['open', 'closed']",

  # user defined filter code function
  'type_match': my_custom_warning_check,
}

needs_warnings must be a dictionary. The dictionary key is used as identifier and gets printed in log outputs. The value must be a valid filter string or a custom defined filter code function and defines a not allowed behavior.

So use the filter string or filter code function to define how needs are not allowed to be configured/used. The defined filter code function must return True or False.

Warning

Assigning a function to a Sphinx option will deactivate the incremental build feature of Sphinx. Please use the Sphinx-Needs API and read Incremental build support for details.

Example output:

...
looking for now-outdated files... none found
pickling environment... done
checking consistency... WARNING: Sphinx-Needs warnings were raised. See console / log output for details.

Checking Sphinx-Needs warnings
  type_check: passed
  invalid_status: failed
      failed needs: 11 (STYLE_005, EX_ROW_1, EX_ROW_3, copy_2, clv_1, clv_2, clv_3, clv_4, clv_5, T_C3893, R_AD4A0)
      used filter: status not in ["open", "in progress", "closed", "done"] and status is not None

  type_match: failed
      failed needs: 1 (TC_001)
      used filter: <function my_custom_warning_check at 0x7faf3fbcd1f0>
done
...

Due to the nature of Sphinx logging, a sphinx-warning may be printed wherever in the log.

needs_warnings_always_warn

If set to True, will allow you to log needs_warnings not passed into a given file if using your Sphinx build command with -w.

Default: False.

For example, set this option to True:

needs_warnings_always_warn = True

Using Sphinx build command sphinx-build -M html {srcdir} {outdir} -w error.log, all the needs_warnings not passed will be logged into a error.log file as you specified.

If you use sphinx-build -M html {srcdir} {outdir} -W -w error.log, the first needs_warnings not passed will stop the build and be logged into the file error.log.

needs_layouts

Added in version 0.5.0.

You can use needs_layouts to define custom grid-based layouts with custom data.

Please read Layouts & Styles for a lot more detailed information.

needs_layouts must be a dictionary and each key represents a layout. A layout must define the used grid-system and a layout-structure.

Example:

needs_layouts = {
    'my_layout': {
        'grid': 'simple',
        'layout': {
            'head': ['my custom head'],
            'meta': ['my first meta line',
                     'my second meta line']
        }
    }
}

Note

Sphinx-Needs provides some default layouts. These layouts cannot be overwritten. See layout list for more information.

needs_default_layout

Added in version 0.5.0.

needs_default_layout defines the layout to use by default.

The name of the layout must have been provided by Sphinx-Needs or by user via configuration needs_layouts.

Default value of needs_default_layout is clean.

needs_default_layout = 'my_own_layout'

needs_default_style

Added in version 0.5.0.

The value of needs_default_style is used as default value for each need which does not define its own style information via :style: option.

See Styles for a list of default style names.

needs_default_layout = 'border_yellow'

A combination of multiple styles is possible:

needs_default_style = 'blue, green_border'

Custom values can be set as well, if your projects provides the needed CSS-files for it.

needs_template_folder

Added in version 0.5.2.

needs_template_folder allows the definition of your own Sphinx-Needs template folder. By default this is needs_templates/.

The folder must already exist, otherwise an exception gets thrown, if a need tries to use a template.

Read also need_template option description for information of how to use templates.

needs_duration_option

Added in version 0.5.5.

Used to define option to store duration information for needgantt.

See also duration_option, which overrides this value for specific needgantt charts.

Default: duration

needs_completion_option

Added in version 0.5.5.

Used to define option to store completion information for needgantt.

See also completion_option, which overrides this value for specific needgantt charts.

Default: completion

needs_services

Added in version 0.6.0.

Takes extra configuration options for Services:

needs_services = {
    'jira': {
        'url': 'my_jira_server.com',
    },
    'git': {
        'url': 'my_git_server.com',
    },
    'my_service': {
        'class': MyServiceClass,
        'config_1': 'value_x',
    }
}

Each key-value-pair in needs_services describes a service specific configuration.

Own services can be registered by setting class as additional option.

Config options are service specific and are described by Services.

See also needservice.

needs_service_all_data

Added in version 0.6.0.

If set to True, data for options which are unknown, is added as string to the need content. If False, unknown option data is not shown anywhere.

Default: False.

needs_service_all_data = True

needs_import_keys

Added in version 4.2.0.

For use with the needimport directive, mapping keys to file paths, see Global keys.

needs_external_needs

Added in version 0.7.0.

Allows to reference and use external needs without having their representation in your own documentation. (Unlike needimport, which creates need-objects from a local needs.json only).

needs_external_needs = [
  {
    'base_url': 'http://mydocs/my_project',
    'json_url':  'http://mydocs/my_project/needs.json',
    'version': '1.0',
    'id_prefix': 'ext_',
    'css_class': 'external_link',
  },
  {
    'base_url': 'http://mydocs/another_project/',
    'json_path':  'my_folder/needs.json',
    'version': '2.5',
    'id_prefix': 'other_',
    'css_class': 'project_x',
  },
  {
    'base_url': '<relative_path_from_my_build_html_to_my_project>/<relative_path_to_another_project_build_html>',
    'json_path':  'my_folder/needs.json',
    'version': '2.5',
    'id_prefix': 'ext_',
    'css_class': 'project_x',
  },
  {
    "base_url": "http://my_company.com/docs/v1/",
    "target_url": "issue/{{need['id']}}",
    "json_path": "needs_test.json",
    "id_prefix": "ext_need_id_",
  },
  {
    "base_url": "http://my_company.com/docs/v1/",
    "target_url": "issue/{{need['type']|upper()}}",
    "json_path": "needs_test.json",
    "id_prefix": "ext_need_type_",
  },
  {
    "base_url": "http://my_company.com/docs/v1/",
    "target_url": "issue/fixed_string",
    "json_path": "needs_test.json",
    "id_prefix": "ext_string_",
  },
]

needs_external_needs must be a list of dictionary elements and each dictionary must/can have the following keys:

base_url:

Base url which is used to calculate the final, specific need url. Normally the path under which the index.html is provided. Base url supports also relative path, which starts from project build html folder (normally where index.html is located).

target_url:

Allows to config the final caculated need url. (optional)
If provided, target_url will be appended to base_url as the final calculate need url, e.g. base_url/target_url. If not, the external need url uses the default calculated base_url.
The target_url supports Jinja context {{need[]}}, need option used as key, e.g {{need['id']}} or {{need['type']}}.

json_url:

An url, which can be used to download the needs.json (or similar) file.

json_path:

The path to a needs.json file located inside your documentation project. Can not be used together with json_url.
The value must be a relative path, which is relative to the project configuration folder (where the conf.py is stored). (Since version 0.7.1)

version:

Defines the version to use inside the needs.json file (optional).

id_prefix:

Prefix as string, which will be added to all id of external needs. Needed, if there is the risk that needs from different projects may have the same id (optional).

css_class:

A class name as string, which gets set in link representations like needtable. The related CSS class definition must be done by the user, e.g. by Own CSS file on sphinx level. (optional) (default: external_link)

needs_needextend_strict

Added in version 1.0.3.

needs_needextend_strict allows you to deactivate or activate the strict option behaviour for all needextend directives.

needs_table_classes

Added in version 0.7.2.

Allows to define custom CSS classes which get set for the HTML tables of need and needtable. This may be needed to avoid custom table handling of some specific Sphinx theme like ReadTheDocs.

needs_table_classes = ['my_custom_class', 'another_class']

These classes are not set for needtables using the table style, which is using the normal Sphinx table layout and therefore must be handled by themes.

needs_builder_filter

Added in version 0.7.2.

Defines a Filter string used to filter needs for the builder needs.

Default is 'is_external==False', so all locally defined need objects are taken into account. Need objects imported via needs_external_needs get sorted out.

needs_builder_filter = 'status=="open"'

needs_build_json

Added in version 0.7.6.

Builds a needs.json file during other builds, like html.

This allows to have one single Sphinx-Build for two output formats, which may save some time.

All other needs.json related configuration values, like needs_file, needs_build_json_per_id and needs_json_remove_defaults are taken into account.

Default: False

Example:

needs_build_json = True

Hint

The created needs.json file gets stored in the outdir of the current builder. So if html is used as builder, the final location is e.g. _build/html/needs.json.

See this section, for an explanation of the output format.

needs_reproducible_json

Added in version 2.0.0.

Setting needs_reproducible_json = True will ensure the needs.json output is reproducible, e.g. by removing timestamps from the output.

needs_json_exclude_fields

Added in version 2.2.0.

Setting needs_json_exclude_fields = ["key1", "key2"] will exclude the given fields from all needs in the needs.json output.

Default: ['lineno_content', 'collapse', 'hide', 'type_prefix', 'type_color', 'type_style', 'id_parent', 'id_complete']

needs_json_remove_defaults

Added in version 2.1.0.

Setting needs_json_remove_defaults = True will remove all need fields with default from needs.json, greatly reducing its size.

The defaults can be retrieved from the needs_schema now also output in the JSON file (see this section for the format).

Default: False

needs_build_json_per_id

Added in version 2.0.0.

Builds list json files for each need. The name of each file is the id of need. This option works like needs_build_json.

Default: False

Example:

needs_build_json_per_id = False

Hint

The created single json file per need, located in needs_build_json_per_id_path folder, e.g _build/needs_id/abc_432.json

needs_build_json_per_id_path

Added in version 2.0.0.

This option sets the location of the set of needs.json for every needs-id.

Default value: needs_id

Example:

needs_build_json_per_id_path = "needs_id"

Hint

The created needs_id folder gets stored in the outdir of the current builder. The final location is e.g. _build/needs_id

needs_build_needumls

Exports needuml data during each build.

This option works like needs_build_json. But the value of needs_build_needumls should be a string, not a boolean. Default value of is: "".

This value of this option shall be a relative folder path, which specifies and creates the relative folder in the outdir of the current builder.

Example:

needs_build_needumls = "my_needumls"

As a result, all the needuml data will be exported into folder in the outdir of the current builder, e.g. _build/html/my_needumls/.

needs_constraints

Added in version 1.0.1.

needs_constraints = {

    "critical": {
        "check_0": "'critical' in tags",
        "check_1": "'security_req' in links",
        "severity": "CRITICAL"
    },

    "security": {
        "check_0": "'security' in tags",
        "severity": "HIGH"
    },

    "team": {
        "check_0": "author == \"Bob\"",
        "severity": "LOW"
    },

}

needs_constraints needs to be enabled by adding “constraints” to needs_extra_options

needs_constraints contains a dictionary which contains dictionaries describing a single constraint. A single constraint’s name serves as the key for the inner dictionary. Inside there are (multiple) checks and a severity. Each check describes an executable constraint which allows to set conditions the specific need has to fulfill. Depending on the severity, different behaviours in case of failure can be configured. See needs_constraint_failed_options

Each need now contains additional attributes named “constraints_passed” and “constraints_results”.

constraints_passed is a bool showing if ALL constraints of a corresponding need were passed.

constraints_results is a dictionary similar in structure to needs_constraints above. Instead of executable python statements, inner values contain a bool describing if check_0, check_1 … passed successfully.

Added in version 2.0.0: The "error_message" key can contain a string, with Jinja templating, which will be displayed if the constraint fails, and saved on the need as constraints_error:

needs_constraints = {

    "critical": {
        "check_0": "'critical' in tags",
        "severity": "CRITICAL",
        "error_message": "need {{id}} does not fulfill CRITICAL constraint, because tags are {{tags}}"
    }

}
.. req::
    :id: SECURITY_REQ

    This is a requirement describing security processes.

.. req::
    :tags: critical
    :links: SECURITY_REQ
    :constraints: critical

    Example of a successful constraint.

.. req::
    :id: FAIL_01
    :author: "Alice"
    :constraints: team

    Example of a failed constraint with medium severity. Note the style from :ref:`needs_constraint_failed_options`
Requirement: SECURITY_REQ
links incoming: R_6F47F

This is a requirement describing security processes.

Requirement: R_6F47F
tags: critical
links outgoing: SECURITY_REQ

Example of a successful constraint.

Requirement: FAIL_01
style: yellow_bar,
author: "Alice"

Example of a failed constraint with medium severity. Note the style from needs_constraint_failed_options

needs_constraint_failed_options

needs_constraint_failed_options = {
    "CRITICAL": {
        "on_fail": ["warn"],
        "style": ["red_bar"],
        "force_style": True
    },

    "HIGH": {
        "on_fail": ["warn"],
        "style": ["orange_bar"],
        "force_style": True
    },

    "MEDIUM": {
        "on_fail": ["warn"],
        "style": ["yellow_bar"],
        "force_style": False
    },

    "LOW": {
        "on_fail": [],
        "style": ["yellow_bar"],
        "force_style": False
    }
}

needs_constraint_failed_options must be a dictionary which stores what to do if a certain constraint fails. Dictionary keys correspond to the severity set when creating a constraint. Each entry describes in an “on_fail” action what to do:

  • “break” breaks the build process and raises a NeedsConstraintFailed Exception when a constraint is not met.

  • “warn” creates a warning in the sphinx.logger if a constraint is not met. Use -W in your Sphinx build command to stop the whole build, if a warning is raised. This will handle all warnings as exceptions.

“style” sets the style of the failed object see Styles for available styles. Please be aware of conflicting styles!

If “force style” is set, all other styles are removed and just the constraint_failed style remains.

needs_variants

Added in version 1.0.2.

needs_variants configuration option must be a dictionary which has pre-defined variants assigned to “filter strings”. The filter string defines which variant a need belongs in the current situations.

For example, in conf.py:

needs_variants = {
  "var_a": "'var_a' in sphinx_tags"  # filter_string
  "var_b": "assignee == 'me'"
}

The dictionary consists of key-value pairs where the key is a string used as a reference to the value. The value is a string which consists of a Python-supported “filter string”.

Default: {}

needs_variant_options

Added in version 1.0.2.

needs_variant_options must be a list which consists of the options to apply variants handling. You can specify the names of the options you want to check for variants.

for example, in conf.py:

needs_variant_options = ["author", "status", "tags"]

From the example above, we apply variants handling to only the options specified.

Default: []

Note

  1. You must ensure the options in needs_variant_options are either default need options or specified in extra options or extra links.

  2. By default, if needs_variant_options is empty, we deactivate variants handling for need options.

needs_render_context

Added in version 1.0.3.

This option allows you to use custom data as context when rendering Jinja templates or strings.

Configuration example:

def custom_defined_func():
    return "my_tag"

needs_render_context = {
    "custom_data_1": "Project_X",
    "custom_data_2": custom_defined_func(),
    "custom_data_3": True,
    "custom_data_4": [("Daniel", 811982), ("Marco", 234232)],
}

The``needs_render_context`` configuration option must be a dictionary. The dictionary consists of key-value pairs where the key is a string used as reference to the value. The value can be any data type (string, integer, list, dict, etc.)

Warning

The value can also be a custom defined function, however, this will deactivate the caching and incremental build feature of Sphinx.

The data passed via needs_render_context will be available as variable(s) when rendering Jinja templates or strings. You can use the data passed via needs_render_context as shown below:

Example 7

.. req:: Need with jinja_content enabled
   :id: JINJA1D8913
   :jinja_content: true

   Need with alias {{ custom_data_1 }} and ``jinja_content`` option set to {{ custom_data_3 }}.

   {{ custom_data_2 }}
   {% for author in custom_data_4 %}
      * author[0]
        + author[1]
   {% endfor %}
Requirement: Need with jinja_content enabled JINJA1D8913

Need with alias Project_X and jinja_content option set to True.

List of contributors:

  • author[0] + author[1]

  • author[0] + author[1]

needs_debug_measurement

Added in version 1.3.0.

Activates Runtime debugging, which measures the execution time of different functions and creates a helpful JSON and HTML report.

See Runtime debugging for details.

To activate it, set it to True:

needs_debug_measurement = True

needs_debug_filters

Added in version 4.0.0.

If set to True, all calls to filter processing will be logged to a debug_filters.jsonl file in the build output directory, appending a single-line JSON for each filter call.