.. _spec_trace:

Traceability
============

References can be specified using the :ref:`refs <spec_attr_refs>` attribute. Backward references
are calculated automatically. These references are shown as :ref:`spec_trace_up_down`.

Categories
----------

*dox_trace* handles the following categories in top-down order:

.. list-table::
    :header-rows: 1

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

.. _spec_trace_up_down:

Upstream and Downstream References
----------------------------------

| :ref:`spec_additional_upstream_references` are (backward) :ref:`refs <spec_attr_refs>`
  **to a higher** category and backward :ref:`refs <spec_attr_refs>` **to the same** category.
| :ref:`spec_additional_downstream_references` are (backward) :ref:`refs <spec_attr_refs>`
  **to a lower** category and explicit :ref:`refs <spec_attr_refs>` **to the same** category.

Example:

.. code-block:: rst

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

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

.. spec:: SWA_stream_id3

.. unit:: SMD_stream_id4

.. _spec_trace_cyclic:

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 :ref:`sources <spec_attr_sources>` can be specified in the *unit* directive.

Example:

.. code-block:: rst

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

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

.. _dox_trace_ref_from_sources:

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.

.. _generate_traceability_report:

Generating Traceability Report
------------------------------

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

.. code-block:: rst

    .. 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:

  .. code-block:: rst

        .. 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 :ref:`traceability_report`, which is specified as follows:

.. literalinclude:: ../examples/report.rst
    :language: rst

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