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 tagLOREM-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
- The special option
- Optional content
- If content is given, it will be parsed as regular ReST.
- A single argument defining the traceable’s tag (
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 (required)- Specify which relationship between traceables to show in the generated matrix.
:filter-primaries:
– traceable filter expression (optional)Specify a filter to limit the primary traceables included in the matrix.
If this option is not given, then all traceables that have one or more relationships of the type specified by
:relationship:
will be included.:filter-secondaries:
– traceable filter expression (optional)Specify a filter to limit the secondary traceables included in the matrix.
If this option is not given, then all traceables that have one or more relationships of the reverse of the type specified by
:relationship:
will be included.:format:
– name of format (optional)Specify the matrix format to generate. The following formats are available:
:format: table
(default)Traditional traceability table format. This format allows the following additional options to be set:
:split-secondaries:
– positive integerThe maximum number of columns to output. If more columns would have been necessary, multiple tables will be generated.
:split-primaries:
– positive integerThe 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.
Showing traceables graphs¶
This section is yet to be written...
[1] | The formal specification of reStructuredText directives is documented here: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives |