Configuration

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

Activation

Add sphinxcontrib.needs to your extensions:

extensions = ["sphinxcontrib.needs",]

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.

needs_template

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 -%}
{{type_name}}: **{{title}}** ({{id}})
    {%- if status and  status|upper != "NONE" and not hide_status %}
    | status: {{status}}
    {%- endif -%}
    {%- if tags and not hide_tags %}
    | tags: {{tags|join("; ")}}
    {%- endif %}
    | links incoming: :need_incoming:`{{id}}`
    | links outgoing: :need_outgoing:`{{id}}`

    {{content|indent(4) }}

{% endif -%}

Available jinja variables are:

  • type
  • type_name
  • type_prefix
  • status
  • tags
  • id
  • links
  • title
  • content
  • hide
  • hide_tags
  • hide_status

Warning

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

needs_diagram_template

This option allows to control the content of diagram elements, which get automatically generated by using .. needfilter:: and :layout: diagram.

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:

<size:12>{{type_name}}</size>\\n**{{title}}**\\n<size:10>{{id}}</size>

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