Sphinx traceability extension
=============================
.. image:: https://badge.fury.io/py/sphinxcontrib-traceability.svg
:target: https://badge.fury.io/py/sphinxcontrib-traceability
Traceability extension for Sphinx documentation generator.
This extension adds directives and roles that serve to identify and
relate portions of Sphinx documents and create lists and traceability
matrices based on them.
It brings Sphinx the capability to work as a pretty decent
document-oriented requirements management tool. Outside of the
requirements domain, it can also be used for a wide range of
documentation needs. Interesting features such as code-documentation
traceability come also out of the box.
Directives
----------
::
.. item:: item_id [item_caption]
:<<relationship>>: other_item_id ...
...
[item_content]
This directive identifies with ``item_id`` the portion of a document
contained by the directive itself (``item_content``). If no
``item_content`` is defined, the directive just marks with ``item_id``
the position of the document where it is defined. An optional text can
be defined with ``item_caption`` and it will be used in cross
references instead of ``item_id``.
The extension also checks for uniqueness of item identifiers through
all files of a Sphinx project, in a similar way to standard Sphinx
references.
The directive allows multiple ``:<<relationship>>:`` options that can
set a list of item identifiers (space separated) the item traces
to. The name of the option itself indicates the type of the
relationship. For example::
.. item:: SW_REQ_001
:addresses: SYS_REQ_001 SYS_REQ_002
:tested_by: SW_TEST_005
:allocated_to: SW_CSU_004
...
There is a predefined set of relationship names that can be used (the
most typical in the systems / software engineering world). If no
specific relationship type is to be set, just the generic ``:trace:``
relationship name can be used.
A configuration variable, ``traceability_relationships``, can be used to
extend and customize the set of available relationships. See
`Configuration`_ for details.
New directive names can be easily added in the configuration file with
the standard Sphinx function ``app.add_directive``. They will be equivalent
to ``item`` but have two big benefits:
- Better document readibility using meaningful names. For example, the
previous software requirement could be directly written as::
.. requirement:: SW_REQ_001
:addresses: SYS_REQ_001 SYS_REQ_002
:tested_by: SW_TEST_005
:allocated_to: SW_CSU_004
...
- Custom templates can be defined for them. This adds a lot of flexibility.
See `Advanced configuration`_ for more details and example configuration
code.
::
.. item-list::
:filter: regexp
This directive generates in place a list of items. A regular
expression can be set with option ``:filter:``, so that only items
whose identifier matches the expression are written in the list.
::
.. item-matrix:: title
:source-title: source title
:source: regexp
:target-title: target title
:target: regexp
:type: <<relationship>> ...
This directive generates in place a traceability matrix of item
cross-references. ``:source:`` and ``:target:`` options can be used to
filter matrix contents. Also content can be filtered based on
traceability relationships. Optional titles can be set for the matrix
itself and for both columns (*"Source"* and *"Target"* are used by
default).
Roles
-----
Whenever an item needs to be referenced in documentation, it can be
done with the ``:item:`` role. This item works the same way as any
other Sphinx cross-reference role. By default, item identifier (or
caption, if existing) shall be used in generated link text, but it can
be overwritten with ``:role:`Text <target>``` Sphinx syntax.
More on relationships
---------------------
When setting a relationship from one item to another, this extension
always considers the reverse relationship and sets it automatically
from the latter to the former.
To do it, the internal relationship dictionary will always require
a name for the reverse relationship. For bidirectional relationships,
the same name shall be used. Examples:
- depends_on: impacts_on
- parent: child
- sibling: sibling
- trace: backtrace
This is a very effective way to make traceability matrices flexible
and easy, as often matrices are requested in both directions. A
traceability matrix from source A to target B according a relationship
will have its automatic reverse matrix form B to A using its reverse
relationship.
Configuration
-------------
``traceability_relationships`` configuration variable follows the rules
above. It is a dictionary with relationship/reverse pairs.
This is the set of predefined relationships (mostly related with
standard UML relationships):
- fulfills: fulfilled_by
- depends_on: impacts_on
- implements: implemented_by
- realizes: realized_by
- validates: validated_by
- trace: backtrace (this is kept mainly for backwards compatibility)
``traceability_data`` configuration variable can be used to add more
options to the item to represent internal data or attributes apart
from relationships. It is a dictionary with name/function pairs. It
follows exactly the same rules as the standard Sphinx and Docutils
``option_spec`` dictionary. Built-in or custom validation/ conversion
functions can be used. See Docutils' `Option Conversion Functions`_.
.. _Option Conversion Functions:
https://docutils.sourceforge.io/docs/howto/rst-directives.html
#option-conversion-functions
Advanced configuration
----------------------
In order to add new directive names, a ``setup`` function
should be added to the configuration file with one call to
``app.add_directive`` per directive. Example:
.. code:: python
def setup(app):
from traceability import ItemDirective
app.add_directive('requirement', ItemDirective)
app.add_directive('test-case', ItemDirective)
...
By default, items are written as term/definition tuples, but this is
fully customizable by defining ``traceability_item_template``
configuration variable. It uses `Jinja2 templating language
<https://jinja.palletsprojects.com>`_.
The template can be customized for each different ``item`` based
directive names. Example:
.. code:: python
traceability_item_template = """
{% if type == 'requirement' %}
:superscript:`[{{ id }}` {{ caption }}:
{{ content }} :subscript:`{{ id }}]`
{% else %}
{{ id }}
{%- if caption %}
**{{ caption }}**
{% endif %}
{{ content|indent(4) }}
{% endif %}
"""
Code above makes the ``requirement`` directive be shown as its caption
& content surrounded with tags ``[<id>`` at the beginning and
``<id>]`` at the end. The rest will be generated as term/definition
tuples, optionally showing its caption.
As an aid for template creation, in verbose mode (putting
``SPHINXOPTS="-v"`` in the Makefile or after the make command) the
extension will print the content generated by the template for every
item.
Examples
--------
There is an `examples` folder with some Sphinx projects you can run.
Raw data
{
"_id": null,
"home_page": "https://github.com/ociu/sphinx-traceability-extension",
"name": "sphinxcontrib-traceability",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "traceability,requirements engineering,requirements management,software engineering,systems engineering,sphinx,requirements",
"author": "Oscar Ciudad",
"author_email": "oscar@jacho.net",
"download_url": "https://files.pythonhosted.org/packages/a6/16/4ce4d1a9684367fe9f95e577dbed4cc934e21759c1633e6620c5ed077827/sphinxcontrib-traceability-0.2.0.tar.gz",
"platform": "any",
"description": "Sphinx traceability extension\n=============================\n\n.. image:: https://badge.fury.io/py/sphinxcontrib-traceability.svg\n :target: https://badge.fury.io/py/sphinxcontrib-traceability\n\nTraceability extension for Sphinx documentation generator.\n\nThis extension adds directives and roles that serve to identify and\nrelate portions of Sphinx documents and create lists and traceability\nmatrices based on them.\n\nIt brings Sphinx the capability to work as a pretty decent\ndocument-oriented requirements management tool. Outside of the\nrequirements domain, it can also be used for a wide range of\ndocumentation needs. Interesting features such as code-documentation\ntraceability come also out of the box.\n\nDirectives\n----------\n\n::\n\n .. item:: item_id [item_caption]\n :<<relationship>>: other_item_id ...\n ...\n \n [item_content]\n\nThis directive identifies with ``item_id`` the portion of a document\ncontained by the directive itself (``item_content``). If no\n``item_content`` is defined, the directive just marks with ``item_id``\nthe position of the document where it is defined. An optional text can\nbe defined with ``item_caption`` and it will be used in cross\nreferences instead of ``item_id``.\n\nThe extension also checks for uniqueness of item identifiers through\nall files of a Sphinx project, in a similar way to standard Sphinx\nreferences.\n\nThe directive allows multiple ``:<<relationship>>:`` options that can\nset a list of item identifiers (space separated) the item traces\nto. The name of the option itself indicates the type of the\nrelationship. For example::\n\n .. item:: SW_REQ_001 \n :addresses: SYS_REQ_001 SYS_REQ_002\n :tested_by: SW_TEST_005\n :allocated_to: SW_CSU_004\n ...\n \nThere is a predefined set of relationship names that can be used (the\nmost typical in the systems / software engineering world). If no\nspecific relationship type is to be set, just the generic ``:trace:``\nrelationship name can be used.\n\nA configuration variable, ``traceability_relationships``, can be used to\nextend and customize the set of available relationships. See\n`Configuration`_ for details.\n\nNew directive names can be easily added in the configuration file with\nthe standard Sphinx function ``app.add_directive``. They will be equivalent\nto ``item`` but have two big benefits:\n\n- Better document readibility using meaningful names. For example, the \n previous software requirement could be directly written as::\n \n .. requirement:: SW_REQ_001 \n :addresses: SYS_REQ_001 SYS_REQ_002\n :tested_by: SW_TEST_005\n :allocated_to: SW_CSU_004\n ...\n \n- Custom templates can be defined for them. This adds a lot of flexibility.\n\nSee `Advanced configuration`_ for more details and example configuration\ncode.\n\n::\n\n .. item-list::\n :filter: regexp\n\nThis directive generates in place a list of items. A regular\nexpression can be set with option ``:filter:``, so that only items\nwhose identifier matches the expression are written in the list.\n\n::\n\n .. item-matrix:: title\n :source-title: source title\n :source: regexp\n :target-title: target title\n :target: regexp\n :type: <<relationship>> ...\n \nThis directive generates in place a traceability matrix of item\ncross-references. ``:source:`` and ``:target:`` options can be used to\nfilter matrix contents. Also content can be filtered based on\ntraceability relationships. Optional titles can be set for the matrix\nitself and for both columns (*\"Source\"* and *\"Target\"* are used by\ndefault).\n\n\nRoles\n-----\n\nWhenever an item needs to be referenced in documentation, it can be\ndone with the ``:item:`` role. This item works the same way as any\nother Sphinx cross-reference role. By default, item identifier (or\ncaption, if existing) shall be used in generated link text, but it can\nbe overwritten with ``:role:`Text <target>``` Sphinx syntax.\n\n\nMore on relationships\n---------------------\n\nWhen setting a relationship from one item to another, this extension\nalways considers the reverse relationship and sets it automatically\nfrom the latter to the former.\n\nTo do it, the internal relationship dictionary will always require\na name for the reverse relationship. For bidirectional relationships,\nthe same name shall be used. Examples:\n\n- depends_on: impacts_on\n- parent: child\n- sibling: sibling\n- trace: backtrace\n\nThis is a very effective way to make traceability matrices flexible\nand easy, as often matrices are requested in both directions. A\ntraceability matrix from source A to target B according a relationship\nwill have its automatic reverse matrix form B to A using its reverse\nrelationship.\n\n\nConfiguration\n-------------\n\n``traceability_relationships`` configuration variable follows the rules\nabove. It is a dictionary with relationship/reverse pairs.\n\nThis is the set of predefined relationships (mostly related with\nstandard UML relationships):\n\n- fulfills: fulfilled_by\n- depends_on: impacts_on\n- implements: implemented_by\n- realizes: realized_by\n- validates: validated_by\n- trace: backtrace (this is kept mainly for backwards compatibility)\n\n``traceability_data`` configuration variable can be used to add more\noptions to the item to represent internal data or attributes apart\nfrom relationships. It is a dictionary with name/function pairs. It\nfollows exactly the same rules as the standard Sphinx and Docutils\n``option_spec`` dictionary. Built-in or custom validation/ conversion\nfunctions can be used. See Docutils' `Option Conversion Functions`_.\n\n.. _Option Conversion Functions:\n https://docutils.sourceforge.io/docs/howto/rst-directives.html\n #option-conversion-functions\n\n\nAdvanced configuration\n----------------------\n\nIn order to add new directive names, a ``setup`` function\nshould be added to the configuration file with one call to\n``app.add_directive`` per directive. Example:\n\n.. code:: python\n\n def setup(app):\n\n from traceability import ItemDirective\n app.add_directive('requirement', ItemDirective)\n app.add_directive('test-case', ItemDirective)\n ...\n\n\nBy default, items are written as term/definition tuples, but this is\nfully customizable by defining ``traceability_item_template``\nconfiguration variable. It uses `Jinja2 templating language\n<https://jinja.palletsprojects.com>`_.\n\nThe template can be customized for each different ``item`` based\ndirective names. Example:\n\n.. code:: python\n\n traceability_item_template = \"\"\"\n {% if type == 'requirement' %}\n :superscript:`[{{ id }}` {{ caption }}:\n {{ content }} :subscript:`{{ id }}]`\n {% else %}\n {{ id }}\n {%- if caption %}\n **{{ caption }}**\n {% endif %}\n {{ content|indent(4) }}\n {% endif %}\n \"\"\"\n\nCode above makes the ``requirement`` directive be shown as its caption\n& content surrounded with tags ``[<id>`` at the beginning and\n``<id>]`` at the end. The rest will be generated as term/definition\ntuples, optionally showing its caption.\n\nAs an aid for template creation, in verbose mode (putting\n``SPHINXOPTS=\"-v\"`` in the Makefile or after the make command) the\nextension will print the content generated by the template for every\nitem.\n\n\nExamples\n--------\n\nThere is an `examples` folder with some Sphinx projects you can run.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Sphinx traceability extension",
"version": "0.2.0",
"project_urls": {
"Download": "https://github.com/ociu/sphinx-traceability-extension/archive/v0.2.0.tar.gz",
"Homepage": "https://github.com/ociu/sphinx-traceability-extension"
},
"split_keywords": [
"traceability",
"requirements engineering",
"requirements management",
"software engineering",
"systems engineering",
"sphinx",
"requirements"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6164ce4d1a9684367fe9f95e577dbed4cc934e21759c1633e6620c5ed077827",
"md5": "e2a04369dd1a945299c83f685df0563f",
"sha256": "f4f8e0eafd34b682f668b6d059d0fe3da776fdba953651847e04f051cc1bc670"
},
"downloads": -1,
"filename": "sphinxcontrib-traceability-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e2a04369dd1a945299c83f685df0563f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23954,
"upload_time": "2023-11-20T01:44:41",
"upload_time_iso_8601": "2023-11-20T01:44:41.849630Z",
"url": "https://files.pythonhosted.org/packages/a6/16/4ce4d1a9684367fe9f95e577dbed4cc934e21759c1633e6620c5ed077827/sphinxcontrib-traceability-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-20 01:44:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ociu",
"github_project": "sphinx-traceability-extension",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "sphinxcontrib-traceability"
}
JSON
