Stakeholders Requirements Specification¶
Introduction¶
Document Purpose¶
This Stakeholders Requirements Specification document identifies the parties interested in the sphinxcontrib-traceables extension, describes their needs, combines the diverse needs in an OpsCon, and derives stakeholder requirements.
This document’s purpose is twofold: on the one hand, to ensure the extension meets its stakeholders’ expectations, and on the other hand, to demonstrate how this extension allows requirements management within Sphinx-based documentation.
Document Scope¶
This document describes the sphinxcontrib-traceables extension. It is limited to stakeholder-level aspects and therefore doesn’t cover technical details.
Document Structure¶
The following chapters describe the stakeholders and their needs, combine those needs into a single OpsCon, and derive stakeholder requirements.
Stakeholders and Their Needs¶
Extension users¶
STKH-USERS
-- Extension users
- children
OPSCON-GRAPHS
,OPSCON-INSTALL
,OPSCON-USAGE
- category
- Stakeholder
This stakeholder represents users of the sphinxcontrib-traceables extension, i.e. people who write Sphinx-based documentation.
This extension adds traceability functionality to Sphinx. Its users can apply such traceability for various different purposes, such as for example:
- Requirements management
Capturing requirements in documentation; tracing the relationships between various types of requirements; generating lists, tables, and diagrams of requirements, and filtering those based on flexible properties of the requirements; tracing requirements to test cases; etc.
- Process descriptions
Describing processes as networks of linked items, i.e. “Process 1 ↦ Artifact A ↦ Process 2 ↦ Artifact B ↦ …”, and keeping the textual description there of in line with diagrams by automatically generating diagrams, tables, relationships, etc. from the textual description.
The users’ needs are that this extension provides the functionality they want and is easy to use:
Desired functionality
Define traceable items and their attributes at arbitrary places within Sphinx documentation
Define relationships between traceable items
Generate lists of traceable items which are flexibly filtered
Generate various output formats showing the relationship between traceable items, such as traceability matrices and graphs
Ease-of-use
Easy installation
Intuitive usage
Informative error messages
These user needs are captured in the OpsCon and stakeholder requirements below.

Traceable graph¶
Extension developers¶
STKH-DEVS
-- Extension developers
- children
OPSCON-DEV
,OPSCON-RELEASE
- category
- Stakeholder
This stakeholder represents developers of the sphinxcontrib-traceables extension, i.e. people who create, expand, and maintain it.
The developers’ needs are that this extension is designed well (easy to expand, easy to maintain, fun to work on, etc.), well documented (easy to understand), and well tested (easy to verify changes don’t break it). Those needs are captured in the OpsCon below.

Traceable graph¶
Operational Concept¶
Developer works on the extension¶
OPSCON-DEV
-- Developer works on the extension
- children
STRQ-CONTINTEGR
,STRQ-DEVDOCS
,STRQ-TESTS
- parents
STKH-DEVS
- category
- OpsConScenario
This scenario covers a developer who works on this extension, expanding its functionality, fixing bugs, writes documentation for it, etc.
Further details for this scenario are yet to be written.
Developer releases the extension¶
OPSCON-RELEASE
-- Developer releases the extension
- children
STRQ-CONTINTEGR
,STRQ-DEVDOCS
,STRQ-TESTS
- parents
STKH-DEVS
- category
- OpsConScenario
This scenario covers a developer who creates a formal release of this
extension and publishes that so that users can install the new release
(see OPSCON-INSTALL
).
Further details for this scenario are yet to be written.
User installs the extension¶
OPSCON-INSTALL
-- User installs the extension
- children
STRQ-PIPINSTALL
,STRQ-USERDOCS
- parents
STKH-USERS
- category
- OpsConScenario
This scenario covers a user who installs this extension. It consists of the following activities:
A
STKH-USERS
reads sphinxcontrib-traceables user documentation, specifically the installation instructions.The
STKH-USERS
uses a standard method to install this extension; standard methods included here:Python’s built-in
pip
tool, i.e.pip install sphinxcontrib-traceables

Stakeholders involved with this scenario and requirements derived from it¶
User writes documentation¶
OPSCON-USAGE
-- User writes documentation with traceables
- children
OPSCON-GRAPHS
,STRQ-CLEARERRMSG
,STRQ-CONFIGRELTYPES
,STRQ-DEFINETRCBLS
,STRQ-SHOWTRACES
,STRQ-SPECGRAPHS
,STRQ-USERDOCS
- parents
STKH-USERS
- category
- OpsConScenario
This scenario covers a user who writes Sphinx-based documentation that contains traceables and other functionality provided by this extension. It consists of the following activities:
A
STKH-USERS
reads sphinxcontrib-traceables user documentation to learn how to use the extension’s functionality.The
STKH-USERS
writes input for Sphinx. The sphinxcontrib-traceables extension provides the following functionality:Define traceable items and their attributes at arbitrary places within Sphinx documentation
Define relationships between traceable items
Generate lists of traceable items which are flexibly filtered
Generate various output formats showing the relationship between traceable items, such as traceability matrices and graphs; see
OPSCON-GRAPHS
for a scenario describing generation of graphs in more detail
The
STKH-USERS
runs Sphinx and generates output.If the input contains errors related to traceables, then this extension gives clear error messages helping the user to quickly understand and fix the error.
User generate graphs showing relationships between traceables¶
OPSCON-GRAPHS
-- User generate graphs showing relationships between traceables
- children
STRQ-SPECGRAPHS
- parents
OPSCON-USAGE
,STKH-USERS
- category
- OpsConScenario
This scenario covers a user wants the output documentation to include generated graphs showing the relationships between traceables.
Example: Show parents and children of a traceable¶
In this example the goal is to show the parents and the children of a given traceable. The desired output graph shows the traceable’s parent hierarchy to one side, and its children hierarchy to the other side.
The maximum length/depth to which the hierarchies are shown should be configurable. If not specified, the complete hierarchies should be shown.
This example includes both parent and child relationships in the output diagram. However, The relationship types are not “mixed”, e.g. it does not show all children of a traceable on the “parent side” of the diagram and vice versa. This leads to a nontrivial specification of which traceables to include.
Example: Hide intermediate traceables while maintaining relationship links¶
This example revolves around a usage scenario where processes and their inputs and outputs are each represented by a traceable. A process is linked to another process by means of one or more of its outputs forming an input for the other process or vice versa.
In this example the goal is to show the relationships between processes, but without including the inputs/outputs in the diagram. In other words, a diagram should be generated showing the linkages between processes without showing the intermediary input/output traceables. Such a diagram could be useful in simplifying the display of linkages between processes without overloading the reader with all the input/output details.
Stakeholder Requirements¶
Requirements for installation and running¶
STRQ-USERDOCS -- High-quality documentation for users |
|
---|---|
children | REQ-INSTALLINSTR |
REQ-USAGEINSTR |
|
parents | OPSCON-INSTALL |
OPSCON-USAGE |
|
category | StakeholderReq |
Users require documentation to help them use this extension. That documentation must cover at least the following topics:
How to install the extension (see
OPSCON-INSTALL
)How to use traceables in their docs (see
OPSCON-USAGE
)How to fix errors if the user incorrectly uses traceables (see
OPSCON-USAGE
)

Traceable graph¶
STRQ-PIPINSTALL -- Easy installation using pip |
|
---|---|
parents | OPSCON-INSTALL |
category | StakeholderReq |
A very common way to install Python packages is to use the pip
tool.
It must therefore be possible for users to easily install this extension
using the pip
tool.

Traceable graph¶
STRQ-CLEARERRMSG -- Clear error messages |
|
---|---|
children | REQ-ERRORMESSAGES |
parents | OPSCON-USAGE |
category | StakeholderReq |
If a user makes an error in his usage of this extension, then this
extension should give a clear error message that helps the user quickly
find and fix the error (see OPSCON-USAGE
).
Sphinx automatically reports on general syntax errors in its input files, usually written in reStructuredText format. This extension therefore does not need to handle such errors.
The error messages to be generated by this extension are mainly related to invalid parameters given to its directives and invalid configuration settings.

Traceable graph¶
Requirements for functionality when writing docs with this extension¶
STRQ-DEFINETRCBLS -- Definition of traceables |
|
---|---|
children | REQ-TRACEDIRECTIVE |
parents | OPSCON-USAGE |
category | StakeholderReq |
A user must be able to define traceables at arbitrary locations within
Sphinx source files using standard reStructuredText constructs
(see OPSCON-USAGE
).
The definition of a traceable must:
Give a unique tag to the traceable, so that it can be referenced throughout the rest of the documentation set
Optionally give a title to the traceable
Optionally define the traceable’s relationships with other traceables
A traceable can have zero or more relationships with other traceables
Each pair of related traceables can be related by one or more relationship types
Optionally arbitrary additional attributes can be defined for the traceable
Examples of additional attributes are: the category, version, color, or foo-value of the traceable
Such attributes can be used to group, filter, arrange, etc. traceables

Traceable graph¶
STRQ-SHOWTRACES -- Generate overviews of traceables, their attributes, and their
relationships |
|
---|---|
children | REQ-TRACEGRAPHS |
REQ-TRACELISTS |
|
REQ-TRACEMATRICES |
|
parents | OPSCON-USAGE |
category | StakeholderReq |
A user must be able to display traceables, their attributes, and their
relationships through out the documentation output.
(see OPSCON-USAGE
).
The following types of output must be supported:
Displays of single traceables and their attributes
Lists of traceables and their attributes
Tables and nested lists showing related traceables
Graphs showing the relationships between traceables

Traceable graph¶
STRQ-SPECGRAPHS -- Flexibly specify which traceables to include in graphs |
|
---|---|
children | REQ-TRACEGRAPHS |
parents | OPSCON-GRAPHS |
OPSCON-USAGE |
|
category | StakeholderReq |
A user must be able to specify in a flexible and powerful way which
traceables to be included in graph output
(see OPSCON-GRAPHS
).
The specification must support at least the usage examples given in the
OPSCON-GRAPHS
scenario.

Traceable graph¶
STRQ-CONFIGRELTYPES -- Configurable relationship types between traceables |
|
---|---|
parents | OPSCON-USAGE |
category | StakeholderReq |
It must be possible to configure the types of relationships that are
valid for a documentation set (see OPSCON-USAGE
).
The valid relationship types can be configured via Sphinx’s standard configuration method, namely in the build configuration file.

Traceable graph¶
Requirements for developers working on this extension¶
STRQ-DEVDOCS -- High-quality documentation for developers |
|
---|---|
parents | OPSCON-DEV |
OPSCON-RELEASE |
|
category | StakeholderReq |
Developers require documentation to help them understand and improve this extension. That documentation must cover at least the following topics:
How this extension is internally structured, so that its workings can easily be understood and so that modifications/improvements will be implemented in-line with its design philosophy (see
OPSCON-DEV
)How to submit modifications/improvements/bug fixes for review and, if accepted, inclusion in the central repository (see
OPSCON-DEV
)How to create and publish a formal release of this extension (see
OPSCON-RELEASE
)

Traceable graph¶
STRQ-TESTS -- High-quality tests of this extension's functionality |
|
---|---|
parents | OPSCON-DEV |
OPSCON-RELEASE |
|
category | StakeholderReq |

Traceable graph¶
STRQ-CONTINTEGR -- Continuous integration setup for this extension |
|
---|---|
parents | OPSCON-DEV |
OPSCON-RELEASE |
|
category | StakeholderReq |