Repository files navigation

Traceability extension for Sphinx documentation generator.

This extension adds directives and roles that serve to identify andrelate portions of Sphinx documents and create lists and traceabilitymatrices based on them.

It brings Sphinx the capability to work as a pretty decentdocument-oriented requirements management tool. Outside of therequirements domain, it can also be used for a wide range ofdocumentation needs. Interesting features such as code-documentationtraceability come also out of the box.

.. item:: item_id [item_caption]   :<<relationship>>:  other_item_id ...   ...   [item_content]

This directive identifies withitem_id the portion of a documentcontained by the directive itself (item_content). If noitem_content is defined, the directive just marks withitem_idthe position of the document where it is defined. An optional text canbe defined withitem_caption and it will be used in crossreferences instead ofitem_id.

The extension also checks for uniqueness of item identifiers throughall files of a Sphinx project, in a similar way to standard Sphinxreferences.

The directive allows multiple:<<relationship>>: options that canset a list of item identifiers (space separated) the item tracesto. The name of the option itself indicates the type of therelationship. 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 (themost typical in the systems / software engineering world). If nospecific relationship type is to be set, just the generic:trace:relationship name can be used.

A configuration variable,traceability_relationships, can be used toextend and customize the set of available relationships. SeeConfiguration for details.

New directive names can be easily added in the configuration file withthe standard Sphinx functionapp.add_directive. They will be equivalenttoitem but have two big benefits:

• Better document readibility using meaningful names. For example, theprevious 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.

SeeAdvanced configuration for more details and example configurationcode.

.. item-list::   :filter: regexp

This directive generates in place a list of items. A regularexpression can be set with option:filter:, so that only itemswhose 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 itemcross-references.:source: and:target: options can be used tofilter matrix contents. Also content can be filtered based ontraceability relationships. Optional titles can be set for the matrixitself and for both columns ("Source" and"Target" are used bydefault).

Whenever an item needs to be referenced in documentation, it can bedone with the:item: role. This item works the same way as anyother Sphinx cross-reference role. By default, item identifier (orcaption, if existing) shall be used in generated link text, but it canbe overwritten with:role:`Text <target>` Sphinx syntax.

When setting a relationship from one item to another, this extensionalways considers the reverse relationship and sets it automaticallyfrom the latter to the former.

To do it, the internal relationship dictionary will always requirea 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 flexibleand easy, as often matrices are requested in both directions. Atraceability matrix from source A to target B according a relationshipwill have its automatic reverse matrix form B to A using its reverserelationship.

traceability_relationships configuration variable follows the rulesabove. It is a dictionary with relationship/reverse pairs.

This is the set of predefined relationships (mostly related withstandard 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 moreoptions to the item to represent internal data or attributes apartfrom relationships. It is a dictionary with name/function pairs. Itfollows exactly the same rules as the standard Sphinx and Docutilsoption_spec dictionary. Built-in or custom validation/ conversionfunctions can be used. See Docutils'Option Conversion Functions.

In order to add new directive names, asetup functionshould be added to the configuration file with one call toapp.add_directive per directive. Example:

defsetup(app):fromtraceabilityimportItemDirectiveapp.add_directive('requirement',ItemDirective)app.add_directive('test-case',ItemDirective)    ...

By default, items are written as term/definition tuples, but this isfully customizable by definingtraceability_item_templateconfiguration variable. It usesJinja2 templating language.

The template can be customized for each differentitem baseddirective names. Example:

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 therequirement 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/definitiontuples, optionally showing its caption.

As an aid for template creation, in verbose mode (puttingSPHINXOPTS="-v" in the Makefile or after the make command) theextension will print the content generated by the template for everyitem.

There is an examples folder with some Sphinx projects you can run.