Usage

Defining traceables

Traceables are defined using the traceable directive described below.

.. traceable:: TAG

Create a traceable item. The TAG should be a unique string throughout the documentation, because it is used to reference the traceable.

The traceable can be given attributes, such as a title, a version, and relationships with other traceables. Attributes are specified using the form :<option-name>: <option-value> [1]. For example, the text below defines a traceable with tag LOREM-IPSUM, title “Lorem ipsum”, and content “Lorem ipsum dolor sit...”:

.. traceable:: LOREM-IPSUM
   :title: Lorem ipsum

   Lorem ipsum dolor sit...

Traceable directives have the following properties:

  • A single argument defining the traceable’s tag (.. traceable:: <TAG>)
    • The tag must be unique throughout the documentation
    • The tag may not contain spaces
  • Zero or more options (:<option-name>: <option-value>)
    • The special option title defines the traceable’s title
    • Options with a valid relationship name define relationships which this traceable has with other traceable
    • Arbitrary option names and values are allowed; if not special options as listed above, the values are stored as traceable attributes and can be used for filtering/querying traceables
  • Optional content
    • If content is given, it will be parsed as regular ReST.

Referencing traceables

Traceables can be referenced using the traceable role described below.

:traceable:

Create a reference to a traceable defined elsewhere in the documentation. For example:

Lorem ipsum :traceable:`LOREM-IPSUM` dolor sit...

Showing traceables matrices

Relationships between traceables can be shown using the traceable-matrix directive described below.

.. traceable-matrix::

Generate a traceables matrix. The matrix shows pairs of traceables which are related to each other by a given relationship (see the :relationship: option below). Various formats are available for showing the pairs of traceables (see the :format: option below).

The following options are available for this directive:

:relationship: – name of traceables relationship
Specify which relationship between traceables to show in the generated matrix.
:format: – name of format

Specify the matrix format to generate. The following formats are available:

  • :format: table Traditional traceability table format. This format allows the following additional options to be set:

    :max-columns: – positive integer

    The maximum number of columns to output. If more columns would have been necessary, multiple tables will be generated.

    :max-rows: – positive integer

    The maximum number of rows to output. If more rows would have been necessary, multiple tables will be generated.

  • :format: columns 2-column table of related traceables

  • :format: list 2-level list of related traceables

For example, the directive shown below would generate a table showing all traceables related to each other with the children relationship:

.. traceable-matrix::
   :relationship: children
   :format: table

The directive shown above creates a traceability matrix as shown below. The image below is a screenshot from the latex-PDF generated for the example project which is part of this extension’s source code.

_images/example-matrix-table.png

Showing traceables graphs

[1]The formal specification of reStructuredText directives is documented here: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives