Traceability

References can be specified using the refs attribute. Backward references are calculated automatically. These references are shown as Upstream and Downstream References.

Categories

dox_trace handles the following categories in top-down order:

Level	Category	Specification Types	Restrictions
5	Input Requirement	requirement / information	category set to input
4	System Requirement	requirement / information	category set to system
3	Software Requirement	requirement / information / srs	for requirement / information: category set to software
2	Architecture	spec / mod / interface	for spec: IDs starting with SWA_
1	Module	spec / unit	for spec: IDs starting with SMD_

Upstream and Downstream References

Upstream References are (backward) refs to a higher category and backward refs to the same category.

Downstream References are (backward) refs to a lower category and explicit refs to the same category.

Example:

.. srs:: SRS_stream_id1

.. spec:: SWA_stream_id2
    :refs: SRS_stream_id1, SWA_stream_id3, SMD_stream_id4

.. spec:: SWA_stream_id3

.. unit:: SMD_stream_id4

[srs] SRS_stream_id1   Status: draft

Asil: not_set | Cal: not_set | Upstream Asil: - | Upstream Cal: - Developer: [missing] | Tester: [missing] | Verification Methods: on_target Tags: - | Upstream Tags: -

[missing]

Verification Criteria: [missing] Derived Feature: - Derived Change Request: -

Upstream References: [missing] Downstream References: SWA_stream_id2

[spec] SWA_stream_id2   Status: draft

Asil: not_set | Cal: not_set | Upstream Asil: not_set | Upstream Cal: not_set Developer: MyCompany | Tester: [missing] | Verification Methods: on_target Tags: - | Upstream Tags: -

[missing]

Verification Criteria: - Derived Feature: - Derived Change Request: - Custom Text: THIS IS THE DEFAULT VALUE Custom Enum: x, y Custom Refs: -

Upstream References: SRS_stream_id1 Downstream References: SMD_stream_id4, SWA_stream_id3

[spec] SWA_stream_id3   Status: draft

Asil: not_set | Cal: not_set | Upstream Asil: not_set | Upstream Cal: not_set Developer: MyCompany | Tester: [missing] | Verification Methods: on_target Tags: - | Upstream Tags: -

[missing]

Verification Criteria: - Derived Feature: - Derived Change Request: - Custom Text: THIS IS THE DEFAULT VALUE Custom Enum: x, y Custom Refs: -

Upstream References: SWA_stream_id2 Downstream References: [missing]

[unit] SMD_stream_id4   Status: draft

Asil: not_set | Cal: not_set | Upstream Asil: not_set | Upstream Cal: not_set Developer: [missing] | Tester: [missing] | Verification Methods: off_target Tags: - | Upstream Tags: -

[missing]

Verification Criteria: - Derived Feature: - Derived Change Request: - Custom Text: THIS IS THE DEFAULT VALUE Custom Enum: x, y

Upstream References: SWA_stream_id2 Downstream References: - Sources: [missing]

Cyclic References

dox_trace checks automatically for cyclic references. A cyclic reference will result in a build error, so it cannot be overlooked if accidentally added.

Cyclic references can only occur on the same level.

References to Source Files

References to sources can be specified in the unit directive.

Example:

.. unit:: SMD_trace_file
    :sources: ../_static/module1/include/source1.h

[unit] SMD_trace_file   Status: draft

Asil: not_set | Cal: not_set | Upstream Asil: - | Upstream Cal: - Developer: [missing] | Tester: [missing] | Verification Methods: off_target Tags: - | Upstream Tags: -

[missing]

Verification Criteria: - Derived Feature: - Derived Change Request: - Custom Text: THIS IS THE DEFAULT VALUE Custom Enum: x, y

Upstream References: [missing] Downstream References: - Sources: ../_static/module1/include/source1.h

References From Source Files

Source files are not touched to add backward references. Instead, a list which maps files back to specifications can be generated in the traceability report.

Generating Traceability Report

A traceability report can be generated by adding the traceability_report directive to an RST file:

.. traceability_report:: <category>
    :developer: <name>

• The <category> can be input, software, architecture, module or source.

• The developer <name> is used to select the entries which shall be shown in the report. It is very common, that the developer is misspelled in the specifications regarding whitespaces and capitalization. Therefore the filtering is tolerant here:

  • case insensitive

  • a space in the <name> matches to 0 or more spaces and underscores

  Example:

  .. traceability_report:: software
      :developer: Abc AG
  
  matches
  
  .. srs:: SRS_Feature_Name1
      :developer: Abc AG
  
  .. srs:: SRS_Feature_Name2
      :developer: ABC_AG
  
  .. srs:: SRS_Feature_Name3
      :developer: AbcAG
  

  The developer option is not relevant for the category source.

This documentation also contains a Traceability Report, which is specified as follows:

.. _traceability_report:

Traceability Report
===================

Input Requirements
------------------

.. traceability_report:: input
    :developer: MyCompany

Software Requirements
---------------------

.. traceability_report:: software
    :developer: MyCompany

Software Architecture
---------------------

.. traceability_report:: architecture
    :developer: MyCompany

Software Module Design
----------------------

.. traceability_report:: module
    :developer: MyCompany

Source Code
-----------

.. traceability_report:: source

For each category, several tables are generated. These tables are predefined and are not meant to be a replacement for e.g. a project status report. Rather, they shall give an overview what is included in the documentation, where references are already specified and where not.

Test Case References

Test case references are not added to the Sphinx documentation. Instead, test cases should be annotated with specification IDs which can be evaluated by an extra tool with the following approach:

• export the specifications to Dim

• using Dim Ruby API to read the specifications

• parsing the test cases

• generating a report