Software Design

Design for mlx.traceability 

DESIGN-TRACEABILITY: Top level design for mlx.traceability

Fulfills

RQT-TRACEABILITY: A plugin for sphinx documentation system, adding traceability

Impacts on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Since the sphinx documentation system is python based, and it allows for plugin development in seperate python packages, python was chosen. No limit should exist on the version of python or sphinx.

@startuml
class TraceableBaseClass {
+ str id
+ str name
+ str caption
+ str docname
+ int lineno
+ docutils.nodes.Node node
+ str content

+ __init__(name)
+ update(other)
+ to_dict()
+ self_test()
}

class TraceableItem {
+ dict explicit_relations
+ dict implicit_relations
+ dict attributes
# bool placeholder

+ __init__(item_id, placeholder=False)
+ __str__(explicit=True, implicit=True)
+ is_placeholder()
+ add_target(relation, target, implicit=False)
+ remove_targets(target_id, explicit=False, implicit=True)
+ iter_targets(relation, explicit=True, implicit=True)
+ iter_relations()
+ define_attribute(attr)
+ add_attribute(attr, value, overwrite=True)
+ remove_attribute(attr)
+ get_attribute(attr)
+ get_attributes(attrs)
+ iter_attributes()
+ is_match(regex)
+ attributes_match(attributes)
+ is_related(relations, target_id)
}

class TraceableAttribute {
+ str value

+ __init__(attr_id, value)
+ can_accept(value)
}

class TraceableCollection {
+ dict relations
+ dict items

+ __init__()
+ __str__()
+ add_relation_pair(forward, reverse='')
+ get_reverse_relation(forward)
+ iter_relations()
+ add_item(item)
+ get_item(item_id)
+ iter_items()
+ has_item(item_id)
+ add_relation(source_id, relation, target_id)
+ export(f_name)
+ self_test(docname=None)
+ are_related(source_id, relations, target_id)
+ get_items(regex, attributes={}, sortattributes=None, reverse=False)
}

abstract class TraceableBaseDirective {
+ {static} final_argument_whitespace = True

+ {abstract} run()
+ process_title(node, default_title='')
+ get_caption()
+ add_found_attributes(node)
+ remove_unknown_attributes(attributes, description, env)
+ check_relationships(relationships, env)
+ check_no_captions_flag(node, no_captions_config)
+ process_options(node, options, env=None)
+ check_option_presence(node, option)
}

class Item2DMatrixDirective {
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = False
}

class ItemAttributeDirective {
+ {static} required_arguments = 1
+ {static} optional_arguments = 1
+ {static} has_content = True
}

class ItemAttributesMatrixDirective {
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = False
}

class ItemDirective {
+ {static} required_arguments = 1
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = True

# store_item_info(target_id, env)
# add_relation_to_ids(relation, source_id, related_ids, env)
# add_attributes(item, env)
}

class ItemLinkDirective {
+ {static} dict option_spec
+ {static} has_content = False
}

class ItemListDirective {
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = False
}

class ItemMatrixDirective {
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = False
}

class ItemPieChartDirective {
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = False

# process_id_set(node, env)
# process_label_set(node)
# process_attribute(node, env)
}

class ItemTreeDirective {
+ {static} optional_arguments = 1
+ {static} dict option_spec
+ {static} has_content = False
}

class ChecklistItemDirective {
+ {static} dict query_results
}

class AttributeSortDirective {
+ {static} dict option_spec
+ {static} has_content = False
}

abstract class TraceableBaseNode {
+ {abstract} perform_replacement(app, collection)
+ {static} create_top_node(title)
+ make_internal_item_ref(app, item_id, caption=True)
+ {static} make_external_item_ref(app, target_text, relationship)
+ is_item_top_level(env, item_id)
+ make_attribute_ref(app, attr_id, value='')
+ has_warned_about_undefined(item_info, env)
# {static} find_colors_for_class(hyperlink_colors, item_id)
}

class Item2DMatrix {
}

class ItemAttribute {
}

class ItemAttributesMatrix {
}

class Item {
# {static} item = None

# process_attributes(dl_node, app)
# process_relationships(collection, *args)
# list_targets_for_relation(relation, targets, dl_node, app)
}

class ItemLink {
}

class ItemList {
}

class ItemMatrix {
}

class ItemPieChart {
+ {static} collection = None
+ {static} relationships = []
+ {static} priorities = {}
+ {static} attribute_id = ''
+ {static} linked_attributes = {}

+ loop_relationships(top_source_id, source_item, pattern, match_function)
+ build_pie_chart(chart_labels, env)
# set_priorities()
# set_attribute_id()
# match_covered(top_source_id, nested_source_item)
# match_attribute_values(top_source_id, nested_target_item)
# prepare_labels_and_values(lower_labels, attributes)
# {static} get_statistics(count_uncovered, count_total)
}

class ItemTree {
# generate_bullet_list_tree(app, collection, item_id, captions=True)
}

class AttributeSort {
}

class PendingItemXref {
}

TraceableBaseClass <|-- TraceableItem
TraceableBaseClass <|-- TraceableAttribute
TraceableItem "1" o-- "N" TraceableAttribute
TraceableCollection "1" o-- "N" TraceableItem
sphinx.environment.BuildEnvironment "1" o-- "1" TraceableCollection
docutils.parsers.rst.Directive <|-- TraceableBaseDirective
TraceableBaseDirective <|-- Item2DMatrixDirective
TraceableBaseDirective <|-- ItemAttributeDirective
TraceableBaseDirective <|-- ItemAttributesMatrixDirective
TraceableBaseDirective <|-- ItemDirective
TraceableBaseDirective <|-- ItemLinkDirective
TraceableBaseDirective <|-- ItemListDirective
TraceableBaseDirective <|-- ItemMatrixDirective
TraceableBaseDirective <|-- ItemPieChartDirective
TraceableBaseDirective <|-- ItemTreeDirective
ItemDirective <|-- ChecklistItemDirective
TraceableBaseNode <|-- docutils.nodes.General
TraceableBaseNode <|-- docutils.nodes.Element
TraceableBaseNode <|-- Item2DMatrix
TraceableBaseNode <|-- ItemAttribute
TraceableBaseNode <|-- ItemAttributesMatrix
TraceableBaseNode <|-- Item
TraceableBaseNode <|-- ItemLink
TraceableBaseNode <|-- ItemList
TraceableBaseNode <|-- ItemMatrix
TraceableBaseNode <|-- ItemPieChart
TraceableBaseNode <|-- ItemTree
TraceableBaseNode <|-- PendingItemXref
Item2DMatrixDirective "1" *-- "1" Item2DMatrix
ItemAttributeDirective "1" *-- "1" ItemAttribute
ItemAttributesMatrixDirective "1" *-- "1" ItemAttributesMatrix
ItemDirective "1" *-- "1" Item
ItemLinkDirective "1" *-- "1" ItemLink
ItemListDirective "1" *-- "1" ItemList
ItemMatrixDirective "1" *-- "1" ItemMatrix
ItemPieChartDirective "1" *-- "1" ItemPieChart
ItemTreeDirective "1" *-- "1" ItemTree
AttributeSortDirective "1" *-- "1" AttributeSort
Exception <|-- TraceabilityException
Exception <|-- MultipleTraceabilityExceptions
@enduml

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Attributes

Effort estimation: 11d

Depends on

DESIGN-TRACEABILITY: Top level design for mlx.traceability

Fulfilled by

IMPL-TRACEABLE_ITEM

Fulfills

RQT-DUMMY_PARENT: Dummy requirement that is not covered by a test

RQT-ITEMIZE: Allow splitting the documentation in parts

Impacts on

DESIGN-ATTRIBUTES: Documentation parts can have attributes

DESIGN-CAPTION: Brief description of documentation part

DESIGN-CONTENT: Content of documentation part

DESIGN-DOCUMENTATION_ID: Identification of documentation part

DESIGN-LIST: Listing documentation parts

DESIGN-RELATIONS: Documentation parts can be linked to each other

A directive name item is added to sphinx through the plugin that allows splitting the documentation into parts. The documentation parts are stored as objects of class TraceableItem. All TraceableItem objects are stored in a container class TraceableCollection.

DESIGN-DOCUMENTATION_ID: Identification of documentation part

Attributes

Effort estimation: 2h

Depends on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Fulfills

RQT-DOCUMENTATION_ID: Identification of documentation part

A first argument to the item directive is used as a unique identifier for the documentation part. The identifier can be any string - not containing spaces.

To ensure uniqueness of the identifier, the TraceableCollection is used. When a TraceableItem will be added to the collection, its identifier is first checked to not appear in the collection yet. If it exists already, a warning is added to the documentation build log.

DESIGN-CAPTION: Brief description of documentation part

Attributes

Effort estimation: 1h

Depends on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Fulfills

RQT-CAPTION: Brief description of documentation part

A second optional argument to the item directive is used as a brief description, or caption of the documentation part. This argument is allowed to have spaces. The caption is stored in the TraceableItem object.

DESIGN-CONTENT: Content of documentation part

Attributes

Effort estimation: 9d 6h

Depends on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Fulfills

RQT-CONTENT: Content of documentation part

The content of the item directive is used as the content of the documentation part. The caption is stored in the TraceableItem object. The content is forwarded through the sphinx parser. So other plugins and/or the native sphinx tool performs conversions from reStructuredText (rst) syntax to docutils nodes.

DESIGN-ATTRIBUTES: Documentation parts can have attributes

Attributes

Effort estimation: 1h 30m

Depends on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Fulfills

RQT-ATTRIBUTES: Documentation parts can have attributes

RQT-ATTRIBUTES_MATRIX: Overview of attributes on documentation parts

RQT-DUMMY_PARENT: Dummy requirement that is not covered by a test

Impacts on

DESIGN-ATTRIBUTES_MATRIX: Overview of attributes on documentation parts

DESIGN-ATTRIBUTE_SORT: Custom sorting of items' attributes

Attributes can be added to the documentation parts. Attributes have a key and an optional value. The set of attributes, their order and the validness of the attribute values are configurable.

DESIGN-RELATIONS: Documentation parts can be linked to each other

Attributes

Effort estimation: 1h

Depends on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Fulfills

RQT-RELATIONS: Documentation parts can be linked to each other

Impacts on

DESIGN-AUTO_REVERSE: Automatic creation of reverse relations

DESIGN-COVERAGE: Calculation of coverage for relations between documentation parts

DESIGN-MATRIX: Auto-generation of a traceability matrix

DESIGN-TREE: Auto-generation of a traceability tree

Documentation parts can be linked to other documentation parts. The set of relations is configurable.

DESIGN-AUTO_REVERSE: Automatic creation of reverse relations

Attributes

Effort estimation: 1h

Depends on

DESIGN-RELATIONS: Documentation parts can be linked to each other

Fulfills

RQT-AUTO_REVERSE: Automatic creation of reverse relations

When a documentation part <A> is related to a documentation part <B> (forward relation), the reverse relation from documentation part <B> to documentation part <A> gets created automatically.

DESIGN-LIST: Listing documentation parts

Attributes

Effort estimation: 1h

Depends on

DESIGN-ITEMIZE: Allow splitting the documentation in parts

Fulfills

RQT-LIST: Listing documentation parts

A list of documentation parts matching a certain query can be retrieved.

DESIGN-COVERAGE: Calculation of coverage for relations between documentation parts

Attributes

Effort estimation: 1h

Depends on

DESIGN-RELATIONS: Documentation parts can be linked to each other

Fulfills

RQT-COVERAGE: Calculation of coverage for relations between documentation parts

The plugin is able to calculate the coverage for a certain type of relation between documentation parts.

DESIGN-MATRIX: Auto-generation of a traceability matrix

Attributes

Effort estimation: 1h

Depends on

DESIGN-RELATIONS: Documentation parts can be linked to each other

Fulfills

RQT-MATRIX: Auto-generation of a traceability matrix

The relations between documentation parts can be queried, and an overview matrix can be generated.

DESIGN-TREE: Auto-generation of a traceability tree

Attributes

Effort estimation: 5h

Depends on

DESIGN-RELATIONS: Documentation parts can be linked to each other

Fulfills

RQT-TREE: Auto-generation of a traceability tree

The relations between documentation parts can be queried, and an overview tree can be generated.

DESIGN-ATTRIBUTES_MATRIX: Overview of attributes on documentation parts

Attributes

Effort estimation: 1h

Depends on

DESIGN-ATTRIBUTES: Documentation parts can have attributes

Fulfills

RQT-ATTRIBUTES_MATRIX: Overview of attributes on documentation parts

An overview table of the attribute values for documentation parts can be generated.

DESIGN-ATTRIBUTE_SORT: Custom sorting of items' attributes

Attributes

Effort estimation: 12h

Depends on

DESIGN-ATTRIBUTES: Documentation parts can have attributes

Fulfills

RQT-ATTRIBUTE_SORT: Custom sorting of items' attributes

The plugin has a directive that allows configurability of the order of items’ attributes.

Traceability matrix 

Tree of design 

Design tree

DESIGN-TRACEABILITY: Top level design for mlx.traceability
- DESIGN-ITEMIZE: Allow splitting the documentation in parts

Effort estimation 

Effort estimation

	Effort estimation
DESIGN-TRACEABILITY: Top level design for mlx.traceability
DESIGN-CAPTION: Brief description of documentation part	1h
DESIGN-RELATIONS: Documentation parts can be linked to each other	1h
DESIGN-AUTO_REVERSE: Automatic creation of reverse relations	1h
DESIGN-LIST: Listing documentation parts	1h
DESIGN-COVERAGE: Calculation of coverage for relations between documentation parts	1h
DESIGN-MATRIX: Auto-generation of a traceability matrix	1h
DESIGN-ATTRIBUTES_MATRIX: Overview of attributes on documentation parts	1h
DESIGN-ATTRIBUTES: Documentation parts can have attributes	1h 30m
DESIGN-DOCUMENTATION_ID: Identification of documentation part	2h
DESIGN-TREE: Auto-generation of a traceability tree	5h
DESIGN-CONTENT: Content of documentation part	9d 6h
DESIGN-ITEMIZE: Allow splitting the documentation in parts	11d
DESIGN-ATTRIBUTE_SORT: Custom sorting of items' attributes	12h

Coverage to requirements and implementation 

Trace design to requirements

Statistics: 14 out of 14 covered: 100%

Design	Linked Requirements	Linked Implementation
DESIGN-ATTRIBUTESDocumentation parts can have attributes	RQT-ATTRIBUTESDocumentation parts can have attributes RQT-ATTRIBUTES_MATRIXOverview of attributes on documentation parts RQT-DUMMY_PARENTDummy requirement that is not covered by a test
DESIGN-ATTRIBUTES_MATRIXOverview of attributes on documentation parts	RQT-ATTRIBUTES_MATRIXOverview of attributes on documentation parts
DESIGN-ATTRIBUTE_SORTCustom sorting of items' attributes	RQT-ATTRIBUTE_SORTCustom sorting of items' attributes
DESIGN-AUTO_REVERSEAutomatic creation of reverse relations	RQT-AUTO_REVERSEAutomatic creation of reverse relations
DESIGN-CAPTIONBrief description of documentation part	RQT-CAPTIONBrief description of documentation part
DESIGN-CONTENTContent of documentation part	RQT-CONTENTContent of documentation part
DESIGN-COVERAGECalculation of coverage for relations between documentation parts	RQT-COVERAGECalculation of coverage for relations between documentation parts
DESIGN-DOCUMENTATION_IDIdentification of documentation part	RQT-DOCUMENTATION_IDIdentification of documentation part
DESIGN-ITEMIZEAllow splitting the documentation in parts	RQT-DUMMY_PARENTDummy requirement that is not covered by a test RQT-ITEMIZEAllow splitting the documentation in parts	IMPL-TRACEABLE_ITEM
DESIGN-LISTListing documentation parts	RQT-LISTListing documentation parts
DESIGN-MATRIXAuto-generation of a traceability matrix	RQT-MATRIXAuto-generation of a traceability matrix
DESIGN-RELATIONSDocumentation parts can be linked to each other	RQT-RELATIONSDocumentation parts can be linked to each other
DESIGN-TRACEABILITYTop level design for mlx.traceability	RQT-TRACEABILITYA plugin for sphinx documentation system, adding traceability
DESIGN-TREEAuto-generation of a traceability tree	RQT-TREEAuto-generation of a traceability tree

Design reverse coverage 

Trace design to requirements

Statistics: 14 out of 14 covered: 100%

Design	Linked Requirements
DESIGN-ATTRIBUTESDocumentation parts can have attributes	RQT-ATTRIBUTESDocumentation parts can have attributes RQT-ATTRIBUTES_MATRIXOverview of attributes on documentation parts RQT-DUMMY_PARENTDummy requirement that is not covered by a test
DESIGN-ATTRIBUTES_MATRIXOverview of attributes on documentation parts	RQT-ATTRIBUTES_MATRIXOverview of attributes on documentation parts
DESIGN-ATTRIBUTE_SORTCustom sorting of items' attributes	RQT-ATTRIBUTE_SORTCustom sorting of items' attributes
DESIGN-AUTO_REVERSEAutomatic creation of reverse relations	RQT-AUTO_REVERSEAutomatic creation of reverse relations
DESIGN-CAPTIONBrief description of documentation part	RQT-CAPTIONBrief description of documentation part
DESIGN-CONTENTContent of documentation part	RQT-CONTENTContent of documentation part
DESIGN-COVERAGECalculation of coverage for relations between documentation parts	RQT-COVERAGECalculation of coverage for relations between documentation parts
DESIGN-DOCUMENTATION_IDIdentification of documentation part	RQT-DOCUMENTATION_IDIdentification of documentation part
DESIGN-ITEMIZEAllow splitting the documentation in parts	RQT-DUMMY_PARENTDummy requirement that is not covered by a test RQT-ITEMIZEAllow splitting the documentation in parts
DESIGN-LISTListing documentation parts	RQT-LISTListing documentation parts
DESIGN-MATRIXAuto-generation of a traceability matrix	RQT-MATRIXAuto-generation of a traceability matrix
DESIGN-RELATIONSDocumentation parts can be linked to each other	RQT-RELATIONSDocumentation parts can be linked to each other
DESIGN-TRACEABILITYTop level design for mlx.traceability	RQT-TRACEABILITYA plugin for sphinx documentation system, adding traceability
DESIGN-TREEAuto-generation of a traceability tree	RQT-TREEAuto-generation of a traceability tree

Implementation coverage 

Trace design to implementation

Statistics: 1 out of 14 covered: 7%

Design	Implementation
DESIGN-ATTRIBUTESDocumentation parts can have attributes
DESIGN-ATTRIBUTES_MATRIXOverview of attributes on documentation parts
DESIGN-ATTRIBUTE_SORTCustom sorting of items' attributes
DESIGN-AUTO_REVERSEAutomatic creation of reverse relations
DESIGN-CAPTIONBrief description of documentation part
DESIGN-CONTENTContent of documentation part
DESIGN-COVERAGECalculation of coverage for relations between documentation parts
DESIGN-DOCUMENTATION_IDIdentification of documentation part
DESIGN-ITEMIZEAllow splitting the documentation in parts	IMPL-TRACEABLE_ITEM
DESIGN-LISTListing documentation parts
DESIGN-MATRIXAuto-generation of a traceability matrix
DESIGN-RELATIONSDocumentation parts can be linked to each other
DESIGN-TRACEABILITYTop level design for mlx.traceability
DESIGN-TREEAuto-generation of a traceability tree

Software Design

Design for mlx.traceability

Traceability matrix

Tree of design

Effort estimation

Coverage to requirements and implementation

Design reverse coverage

Implementation coverage

Design for mlx.traceability 

Traceability matrix 

Tree of design 

Effort estimation 

Coverage to requirements and implementation 

Design reverse coverage 

Implementation coverage 