Configuration

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

Activation

Add sphinxcontrib.needs to your extensions:

extensions = ["sphinxcontrib.needs",]

Incremental build support

Sphinx does not use its incremental build feature, if functions are assigned 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 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 sphinxcontrib.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 options starts with the prefix needs_ for this extension.

needs_include_needs

Set this option on 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 “req”, which can be used via .. req:: in documents

  • title: Title, which is 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.

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

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

New in version 0.2.2.

The option allows the addition of extra options that can be specified on needs.

It can be specified 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

Default value = {'hidden': directives.unchanged}

The hidden option is a globally available option, which is always hidden and can be used to easily execute Dynamic functions.

Extra options automatically appear in needs, if a value is set. By using needs_hide_options the output of such options can be hidden.

Note

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

Show example

conf.py

1from docutils.parsers.rst import directives
2
3needs_extra_options = {
4   "my_extra_option": directives.unchanged,
5   "another_option": directives.unchanged,
6   }

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

.. needfilter::
   :filter: "filter_me" in another_option

Result

Requirement: My requirement with custom options xyz_123 _images/arrow-right-circle.svg
status: open
my_extra_option: A new option
another_option: filter_me

Some content

Before version 0.7.2 needs_extra_options needs to be a dict and using directives.unchanged as value. But this has broken the Sphinx incremental build feature. Please read Incremental build support for details.

Configuration before 0.7.2 (do not use for newer versions!):

from docutils.parsers.rst import directives

 needs_extra_options = {
  "introduced": directives.unchanged,
  "updated": directives.unchanged,
  "impacts": directives.unchanged
 }

needs_global_options

New in version 0.3.0.

Global options are set on global level for all needs, so that all needs get the same value for the configured option.

needs_global_options = {
   'global_option': 'Fix value'
}

Default value = {}

Combined with Dynamic functions this can be a powerful method to automate data handling:

needs_global_options = {
      'global_option': '[[copy("id")]]'
}

Filter based global options

New in version 0.4.3.

The value of a global_option can be also set only, if a given Filter string is passed. If it is not passed, the option is not set or a given default value is set.

To use filters for global_options, the given value must be a tuple, containing the following elements:

  1. value to set (required)

  2. filter string, which must be passed (required)

  3. default value, if filter string is not passed (optional)

needs_global_options = {
   # Without default value
   'status': ('closed', 'status.lower() in ["done", "resolved", "closed"]')

   # Set Marco as author if security tag is used. In all other cases set Daniel as author.
   'author': ('Marco', '"security" in tags', 'Daniel)

   # Dynamic functions are allowed as well
   'req_id': ('[[copy("id")]]', 'id.startswith("REQ_")')
}

There are use cases, for which an option needs to get different values based on different filter. In this cases you can provide a list of tuples:

needs_global_options = {
      # Without default value
      'status': [
            ('fulfilled', 'status.lower() in ["done", "resolved", "closed"]', 'type=="req"'),
            ('done', 'status.lower() in ["done", "resolved", "closed"]', 'type=="task"'),
            ('implemented', 'status.lower() in ["done", "resolved", "closed"]', 'type=="spec"')
      ]
   }

Warning

The filter string gets executed against the current need only and has no access to other needs. That’s because the global_options get set during initialisation of the document and during this phase not every document has been already read by Sphinx.

So avoid any references to other needs in the filter string.

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

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 execued 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 poweful together with internal needs info 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": directives.unchanged,
}

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_flow_configs

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

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

@startuml ' Config 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 { 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 } 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

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

needs_diagram_template

This option allows to control the content of diagram elements, which get automatically generated by using .. needflow:: / needflow.

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

New in version 0.1.19.

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

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

needs_id_required = True

By default this option is set to False.

If an ID is missing sphinx throws the exception “NeedsNoIdException” and stops the build.

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_title_optional

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

.. req::
    :title_from_content:

    This will be my 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: This will be my title R_D8F29 _images/arrow-right-circle.svg

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

needs_title_from_content

New 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 of the requirement. The length of the title will adhere to the needs_max_title_length setting (which is not limited by default).

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:

.. req::

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

This will be rendered the first sentence as the title

Requirement: R_34265 _images/arrow-right-circle.svg

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 a maximum length is provided and the generated title would exceed that limit, then an elided version of the title will be used.

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 _images/arrow-right-circle.svg

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

New 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

New in version 0.1.41.

Defines a set of valid statuses, which are allowed to be used inside documentation. If a not defined status is detected, 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

New in version 0.1.41.

Defines a set of valid tags, which are allowed to be used inside documentation. If a not defined tag is detected, 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

New 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

New in version 0.1.48.

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

If the role need is used, 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

New 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

New 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

New 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

New in version 0.2.0.

Defines a regular expression, which is used to validate all manual set IDs and to generate valid IDs for needs without a given ID.

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

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 an manually given ID does 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

New in version 0.3.0.

Used to register own dynamic functions.

Must be a list of python functions.

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.

Better use the following way in our conf.py file:

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

New 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

New 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

This option if set to True, will allow to log not passed needs_warnings 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 not passed needs_warnings will be logged into file error.log as you specified.

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

needs_layouts

New in version 0.5.0.

needs_layouts is used to define own 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 can not be overwritten. See layout list for more information.

needs_default_layout

New in version 0.5.0.

needs_default_layout defines the layout to be used by default.

The used layout name must be one provided already by Sphinx-Needs or one provided by user via configuration needs_layouts.

Default value of needs_default_layout is clean.

needs_default_layout = 'my_own_layout'

needs_default_style

New 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

New 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

New in version 0.5.5.

Used to define option, which shall be used to store duration information for needgantt.

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

Default: duration

needs_completion_option

New in version 0.5.5.

Used to define option, which shall be used to store completion information for needgantt.

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

Default: completion

needs_services

New 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

New 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_external_needs

New 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',
  }
]

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

json_url

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

json_path

A path to a locally stored needs.json file. Can not be used together with json_url. A relative path must be 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_table_classes

New 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']

Default: ['rtd-exclude-wy-table', 'no-sphinx-material-strip']

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

The following themes support the following table classes to deactivate their specific handling:

Theme

Class

ReadTheDocs

rtd-exclude-wy-table

Sphinx-Material

no-sphinx-material-strip

Hint

The deactivation of theme specific table handling is quite a new feature in most themes. Please be sure to use the newest theme version or even the nightly build.

needs_builder_filter

New in version 0.7.2.

Defines a Filter string, which is 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

New in version 0.7.6.

Builds a needs.json file also 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, are taken into account.

Example:

needs_build_json = True

Default: False

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.

Removed options

The following options are no longer supported, if the latest version of sphinx-needs is used.

needs_template

removed: 0.3.0

The layout of needs can be fully customized by using jinja.

If nothing is set, the following default template is used:

.. _{{id}}:

{% if hide == false -%}
.. role:: needs_tag
.. role:: needs_status
.. role:: needs_type
.. role:: needs_id
.. role:: needs_title

.. rst-class:: need
.. rst-class:: need_{{type_name}}

.. container:: need

    :needs_type:`{{type_name}}`: :needs_title:`{{title}}` :needs_id:`{{id}}`
        {%- if status and  status|upper != "NONE" and not hide_status %}
        | status: :needs_status:`{{status}}`
        {%- endif -%}
        {%- if tags and not hide_tags %}
        | tags: :needs_tag:`{{tags|join("` :needs_tag:`")}}`
        {%- endif %}
        | links incoming: :need_incoming:`{{id}}`
        | links outgoing: :need_outgoing:`{{id}}`

        {{content|indent(8) }}

{% endif -%}

Available jinja variables are:

  • type

  • type_name

  • type_prefix

  • status

  • tags

  • id

  • links

  • title

  • content

  • hide

Warning

You must add a reference like .. _{{id}}: to the template. Otherwise linking will not work!

needs_template_collapse

removed: 0.3.0

Defines a template, which is used for need with active option collapse.

Default value:

 .. _{{id}}:

 {% if hide == false -%}
.. role:: needs_tag
.. role:: needs_status
.. role:: needs_type
.. role:: needs_id
.. role:: needs_title
.. rst-class:: need
.. rst-class:: need_{{type_name}}

.. container:: need

    .. container:: toggle

        .. container:: header

            :needs_type:`{{type_name}}`: :needs_title:`{{title}}` :needs_id:`{{id}}`
            :needs_type:`{{type_name}}`: :needs_title:`{{title}}` :needs_id:`{{id}}`
        {%- if status and  status|upper != "NONE" and not hide_status %}
        | status: :needs_status:`{{status}}`
        {%- endif -%}
        {%- if tags and not hide_tags %}
        | tags: :needs_tag:`{{tags|join("` :needs_tag:`")}}`
        {%- endif %}
        | links incoming: :need_incoming:`{{id}}`
        | links outgoing: :need_outgoing:`{{id}}`

    {{content|indent(4) }}

{% endif -%}

For more details please see needs_template.

needs_hide_options

New in version 0.3.0.

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 :ref:layouts_styles for more information.

Can be used to hide specific options from general output in rendered document:

needs_hide_options = ['tags', 'global_option']

Works with local set options, extra options and global options.

Default value: ['hidden']

The hidden option is a globally available option, which is always hidden and can be used to easily execute Dynamic functions.

Combined with Dynamic functions and needs_global_options this configuration can be used to perform complex calculations in the background and hide any output.

needs_collapse_details

New in version 0.2.0.

removed: 0.5.0

Note

Starting with version 0.5.0 the used layout decides, what the default behavior is. To customize this behavior, you have to create your own layout.

If true, need details like status, tags or links are collapsed and shown only after a click on the need title.

# conf.py
needs_collapse_details = False

Default value: True

Can be overwritten for each single need by setting collapse.