Sphinx needs extension for managing needs/requirements and specifications
Project description
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).
.. code-block:: rst
.. 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
---------
::
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
.. _need_types:
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 <http://jinja.pocoo.org/>`_.
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 in :ref:`need_types`.
needfilter
----------
Example::
.. needfilter::
:status: open;in_progress
:tags: user; login
: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:** and **:tags:** values are separated by "**;**". The logic is as followed::
status = (open OR in_progress) AND tags = (user OR login)
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`.
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).
.. code-block:: rst
.. 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
---------
::
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
.. _need_types:
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 <http://jinja.pocoo.org/>`_.
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 in :ref:`need_types`.
needfilter
----------
Example::
.. needfilter::
:status: open;in_progress
:tags: user; login
: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:** and **:tags:** values are separated by "**;**". The logic is as followed::
status = (open OR in_progress) AND tags = (user OR login)
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`.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Close
Hashes for sphinxcontrib-needs-0.1.11.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 96a00a253c9f14abcb4b3a7963655a4d5e5c3bc3fba15788a8543f7efd9e05a4 |
|
| MD5 | bade54b7b153f26df931708eb3d31ef5 |
|
| BLAKE2b-256 | da06ac9b47959ff95f8a6780c322b8687ef50e2e150ed9b69af1f16d659a8b76 |
