sphinxcontrib-needs 0.1.13

Sphinx needs extension for managing needs/requirements and specifications

This package contains the needs Sphinx extension.

It allows the definition, linking and filtering of need-objects, which are by default:

• requirements

• specifications

• implementations

• test cases.

This list can be easily customized via configuration (for instance to support bugs or user stories).

.. req:: My first requirement
   :status: open
   :tags: requirement; test; awesome

   This is my **first** requirement!!
   .. note:: It's awesome :)

.. spec:: Specification of a requirement
   :id: OWN_ID_123

.. impl:: Implementation for specification
   :id: impl_01
   :links: OWN_ID_123

.. test:: Test for XY
   :status: implemented
   :tags: test; user_interface; python27
   :links: OWN_ID_123; impl_01

   This test checks the implementation of :ref:`impl_01` for spec :ref:`OWN_ID_123` inside a
   Python 2.7 environment.

Each need can contain:

• a title (required)

• an unique id (optional. Gets calculated based on title if not given)

• a description, which supports fully rst and sphinx extensions (optional)

• a status (optional)

• several tags (optional)

• several links to other needs (optional)

You can create filterable overviews of defined needs by using the needfilter directive:

.. needfiler::
   :status: open;in_progress
   :tags: tests; test; test_case;
   :layout: table

Contents

• Installation

  • Using pip

  • Using sources

• conf.py

  • Activation

  • Options

    • needs_include_needs

    • needs_id_length

    • needs_types

    • needs_template

• Directives

  • req (or any other defined need type)

  • needfilter

Installation

Using pip

pip install sphinxcontrib-needs

Using sources

git clone https://github.com/useblocks/sphinxcontrib-needs
python setup.py install

conf.py

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_"),
           dict(directive="spec", title="Specification", prefix="S_"),
           dict(directive="impl", title="Implementation", prefix="I_"),
           dict(directive="test", title="Test Case", prefix="T_"),
           ]

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 “”

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

    {{content|indent(4) }}

    {% if status and not hide_status -%}
    **status**: {{status}}
    {% endif %}

    {% if tags and not hide_tags -%}
    **tags**: {{"; ".join(tags)}}
    {% endif %}

    {% if links -%}
    **links**:
    {% for link in links -%}
        :ref:`{{link}} <{{link}}>` {%if loop.index < links|length -%}; {% endif -%}
    {% endfor -%}
    {% endif -%}
{% 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 reference like .. _{{id}}: to the templates. Otherwise linking will not work!

Directives

req (or any other defined need type)

Example:

.. req:: User needs to login
   :id: ID123
   :status: open
   :tags: user;login
   :links: ID444; ID_555

   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.

However, 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.

Tags must be separated by “;”, like tag1; tag2;tag3. Whitespaces get removed.

links can be used to create a link to one or several other needs, no matter what kind of type they are. All you need is the related ID.

There is an additional 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!

You can also use :hide_status: and :hide_tags: ti hide the related information for this need.

Note

By default the above example works also with .. spec::, .. impl::, .. test:: and all other need types, which are configured via needs_types.

needfilter

Example:

.. needfilter::
   :status: open;in_progress
   :tags: user; login
   :types: req;spec
   :show_status:
   :show_tags:
   :show_filters:
   :sort_by: id
   :layout: list

This prints a list with all found needs, which match the filters for status and tags.

For :status:, :tags: and :types: values are separated by “;”. The logic is as followed:

status = (open OR in_progress) AND tags = (user OR login) AND types = (req OR spec)

If :show_status: / :show_tags: is given, the related information will be shown after the name of the need.

To show the used filters under a list, set :show_filters:

The showed list is unsorted as long as the parameter :sort_by:: is not used. Valid options for :sort_by: are id and status.

Instead of a list you can also get a table by setting :layout: table.