search

ociu / sphinx-traceability-extension

Traceability extension for Sphinx documentation generator
GNU General Public License v3.0
30 stars 13 forks source link

Requirement Traceability Matrix #7

Closed fkromer closed 6 years ago

fkromer commented 8 years ago

Have you thought about to add the generation of a requirement traceability matrix (like done here) or to provide a data interface that one may generate one externally? Or both... I would be interested in contribution.

ociu commented 8 years ago

The item_matrix directive already generates a traceability matrix. It is not bidimensional as your example, but a two column table with related items. Nevertheless, it can be used for the same purpose.

If you build the example document you can see how traceability matrices are created.

SteinHeselmans commented 6 years ago

I think this feature is available in melexis fork: https://github.com/melexis/sphinx-traceability-extension#2d-matrix-of-documentation-items

Example: https://melexis.github.io/sphinx-traceability-extension/#item-2d-matrix

implemented in https://github.com/melexis/sphinx-traceability-extension/pull/40 and https://github.com/melexis/sphinx-traceability-extension/pull/41

backporting could be more difficult as the data organization is class based in melexis fork...

fkromer commented 6 years ago

@SteinHeselmans Nice work. Is it possible to get the data out e.g. that it can be represented differently in some custom website as well? Could you point to the sources of the data organization? (If operations are executed on the data it makes totally sense to use classes. If no operation needs to be executed on the data Namedtuples could be good choices for data representation as well.)

SteinHeselmans commented 6 years ago

There is no explicit way to change the representation of the directives in melexis fork. I know the origin ociu-version has a template for representing an item, but that support is removed in the melexis fork. So also the item-2d-matrix is not templated... I am not an html expert myself, but some customization should be possible with css/javascript, probably. A colleague of mine is using some javascript on top to color the items and links to them based on their name...

There is operations on the data in melexis fork: if a forward link is created from item a to item b, the reverse link from item b to item a is also added. If item b does not exist yet in the collection, a placeholder for it is added. In the end no placeholders should exist (broken links). Hiding these things in classes (traceable_item.py and traceable_collection.py) makes the whole thing better to read, unit test, and maintain. See readme, test cases and inline code docs for more details on data organization in melexis fork. I will push the use of classes even further in our melexis fork, as the CCM values are way too high now.

fkromer commented 6 years ago

@SteinHeselmans

I know the origin ociu-version has a template for representing an item, but that support is removed in the melexis fork. So also the item-2d-matrix is not templated... I am not an html expert myself, but some customization should be possible with css/javascript, probably.

As far as I can remember the template was somehow limited anyway. I prefer css/javascript.

There is operations on the data in melexis fork: if a forward link is created from item a to item b, the reverse link from item b to item a is also added. If item b does not exist yet in the collection, a placeholder for it is added. In the end no placeholders should exist (broken links).

Nice (and definitely required) feature!

Hiding these things in classes (traceable_item.py and traceable_collection.py) makes the whole thing better to read, unit test, and maintain. See readme, test cases and inline code docs for more details on data organization in melexis fork.

Would have been my design choice as well. As soon as requirement traceability for our Python source code would get required I consider to use your fork. Would be nice to beeing able to install your fork via PyPi. But tagged versions on github are fine for me as well.

I will push the use of classes even further in our melexis fork, as the CCM values are way too high now.

Thx in advance :wink:

SteinHeselmans commented 6 years ago

how about https://pypi.org/project/mlx.traceability/ :wink:

check the readme for details of installing and your makefile/conf.py : pip install mlx.traceability