System Requirements Specification¶

Introduction¶

Document Purpose¶

This System Requirements Specification document…

This document’s purpose is twofold: on the one hand, to provide clear requirements for development of this extension, and on the other hand, to demonstrate how this extension allows requirements to be captured within Sphinx-based documentation.

Document Scope¶

This document describes the sphinxcontrib-traceables extension. It is limited to system-level aspects.

Document Structure¶

The following chapters describe…

Stakeholder Requirements¶

The Stakeholders Requirements Specification defined the following stakeholder requirements:

Tag	Title
`STRQ-CLEARERRMSG`	Clear error messages
`STRQ-CONFIGRELTYPES`	Configurable relationship types between traceables
`STRQ-CONTINTEGR`	Continuous integration setup for this extension
`STRQ-DEFINETRCBLS`	Definition of traceables
`STRQ-DEVDOCS`	High-quality documentation for developers
`STRQ-PIPINSTALL`	Easy installation using pip
`STRQ-SHOWTRACES`	Generate overviews of traceables, their attributes, and their relationships
`STRQ-SPECGRAPHS`	Flexibly specify which traceables to include in graphs
`STRQ-TESTS`	High-quality tests of this extension's functionality
`STRQ-USERDOCS`	High-quality documentation for users

System Requirements¶

Functional Requirements¶

REQ-TRACEDIRECTIVE -- Traceables can be defined using reST directive

children: TEST-TRACEDEF
parents: STRQ-DEFINETRCBLS
category: SysReq
requirement_type: functional
verification_method: ci-test

It must be possible to define a traceable using a reST directive.

Directive options define the traceable’s attributes. Certain option keys have special meaning:

:title: sets the traceable’s title attribute
Options with the name of a valid relationship define the traceable’s relationships with other traceables

Directive content defines arbitrary information that is associated with the traceable. It is shown in line where the traceable is displayed in full, but otherwise not used in traceable processing, filtering, etc. The content is parsed as reST code.

Traceable graph¶

REQ-TRACELISTS -- Lists can be generated showing traceables and their attributes

parents: STRQ-SHOWTRACES
category: SysReq
requirement_type: functional
verification_method: ci-test

It must be possible to generate lists of traceables using a reST directive. The directive’s options allow filtering and formatting of the output.

Traceable graph¶

`REQ-TRACEMATRICES` -- Matrices can be generated showing relationships between traceables
parents	`STRQ-SHOWTRACES`
category	SysReq
requirement_type	functional
verification_method	ci-test

It must be possible to generate matrices of traceables using a reST directive. The directive’s options allow filtering and formatting of the output.

Traceable graph¶

REQ-TRACEGRAPHS -- Graphs can be generated showing relationships between traceables

children: TEST-GRAPHHTML, TEST-GRAPHNOSTARTTAGS, TEST-GRAPHXML
parents: STRQ-SHOWTRACES, STRQ-SPECGRAPHS
category: SysReq
requirement_type: functional
verification_method: ci-test

Traceable graph¶

REQ- -- REQ-

parents: STRQ-
category: SysReq
requirement_type: functional
verification_method: ci-test

Traceable graph¶

Usability requirements¶

REQ-ERRORMESSAGES -- Helpful error messages are generated upon incorrect usage of this extension

children: TEST-GRAPHNOSTARTTAGS, TEST-TRACEDEF
parents: STRQ-CLEARERRMSG
category: SysReq
requirement_type: usability
verification_method: ci-test

Traceable graph¶

Documentation Requirements¶

REQ-INSTALLINSTR -- User docs contain installation instructions

parents: STRQ-USERDOCS
category: SysReq
requirement_type: documentation
verification_method: doc-review

Traceable graph¶

REQ-USAGEINSTR -- User docs contain usage instructions

parents: STRQ-USERDOCS
category: SysReq
requirement_type: documentation
verification_method: doc-review

The user documentation must describe how to use the features provided by this extension. It must cover at least all features as stated by the functional requirements:

REQ- REQ-
REQ-TRACEDIRECTIVE Traceables can be defined using reST directive
REQ-TRACEGRAPHS Graphs can be generated showing relationships between traceables
REQ-TRACELISTS Lists can be generated showing traceables and their attributes
REQ-TRACEMATRICES Matrices can be generated showing relationships between traceables

Traceable graph¶

Traceability¶

	`REQ-ERRORMESSAGES`	`REQ-INSTALLINSTR`	`REQ-TRACEDIRECTIVE`	`REQ-TRACEGRAPHS`	`REQ-TRACELISTS`	`REQ-TRACEMATRICES`	`REQ-USAGEINSTR`
`STRQ-CLEARERRMSG`	✔
`STRQ-CONFIGRELTYPES`
`STRQ-CONTINTEGR`
`STRQ-DEFINETRCBLS`			✔
`STRQ-DEVDOCS`
`STRQ-PIPINSTALL`
`STRQ-SHOWTRACES`				✔	✔	✔
`STRQ-SPECGRAPHS`				✔
`STRQ-TESTS`
`STRQ-USERDOCS`		✔					✔

List of system requirements:

Tag	Title	Verification_method
`REQ-`	REQ-	ci-test
`REQ-ERRORMESSAGES`	Helpful error messages are generated upon incorrect usage of this extension	ci-test
`REQ-INSTALLINSTR`	User docs contain installation instructions	doc-review
`REQ-TRACEDIRECTIVE`	Traceables can be defined using reST directive	ci-test
`REQ-TRACEGRAPHS`	Graphs can be generated showing relationships between traceables	ci-test
`REQ-TRACELISTS`	Lists can be generated showing traceables and their attributes	ci-test
`REQ-TRACEMATRICES`	Matrices can be generated showing relationships between traceables	ci-test
`REQ-USAGEINSTR`	User docs contain usage instructions	doc-review