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- Specify which relationship between traceables to show in the generated matrix.
:format:
– name of formatSpecify 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 integerThe maximum number of columns to output. If more columns would have been necessary, multiple tables will be generated.
:max-rows:
– 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¶
[1] | The formal specification of reStructuredText directives is documented here: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives |