item-matrix should support the same categories as item-piechart

[gcrabbe]

In my project, I have the following instance of item-piechart:

.. item-piechart:: Unit requirement pie chart
    :id_set: RQT- TC- TR-
    :label_set: UNCOVERED, COVERED, EXECUTED
    :sourcetype: validated_by
    :targettype: tested_by
    :scope: UNIT
    :result: FAILED, PASSED
    :colors: #b2c4cb #eea320 #b2c4cb #db4140 #65bba9

Which gives the following pie chart:

I also have an item-matrix with the same requirements as the pie chart:

.. item-matrix:: Unit requirement matrix
    :source: RQT-
    :intermediate: TC-
    :target: TR-
    :sourcetitle: Requirement
    :intermediatetitle: Testcase
    :targettitle: Test record
    :type: validated_by | tested_by
    :scope: UNIT
    :targetcolumns: result
    :coveredintermediates:
    :splitintermediates:

I would like to split my matrix into the same five subsections (or into five submatrices) as the pie chart. However, the item-matrix directive currently only provides the onlyuncovered and onlycovered filters. The first filter gives me the sum of UNCOVERED and COVERED, while the second gives me the rest.

[JasperCraeghs]

I don't see a way to extend the item-matrix-directive to support this use case. Do you, @Letme?

[Letme]

I think I understand the request, but let me clarify, because onlycovered and onlyuncovered are not what we actually wanted to expose. I think the idea is to make it more flexible, and not avoid on covered/non covered filters, but maybe have something like set_label in combination with type (result)?

Can we maybe see a way for pie-chart directive to print the details?

[gcrabbe]

The (somewhat unfortunate) naming convention in my project is the following:

State	Meaning
UNCOVERED	Testcase missing
COVERED	Testcase present, Test Record missing
EXECUTED	Testcase present, Test Record present, Result attribute missing
FAILED	Testcase present, Test Record present, Result attribute set to FAILED
PASSED	Testcase present, Test Record present, Result attribute set to PASSED

---

The first thing that's missing is a filter for the COVERED state. I can play around with coveredintermediates, but there is no way to isolate COVERED requirements in a matrix of their own, as seen below:

Filter	Result
:onlyuncovered:	UNCOVERED
:onlyuncovered:, :coveredintermediates:	UNCOVERED, COVERED
:onlycovered:	COVERED, EXECUTED, FAILED, PASSED
:onlycovered:, :coveredintermediates:	EXECUTED, FAILED, PASSED

---

The second thing that's missing is an <<attribute>> with multiple arguments, as exists for item-piechart:

.. item-matrix:: Unit requirement matrix
    [...]
    :result: FAILED, PASSED
    [...]

---

The "five submatrices" approach, which is perhaps the simplest, would be to modify the group attribute to:

• Create a subgroup for every state, including intermediate ones
• Display a subheader for each subgroup
• Rename top/bottom to descending/ascending or something to that effect

---

The "five matrices" approach would require:

• Three new filters, hideuncovered, hidehalfcovered, and hidecovered, that one could OR together for the desired result
• A hidebyattribute filter with the same multiple arguments as <<attribute>>
• Either a special value for hidebyattribute or a separate hidemissingattribute flag (issue item-piechart <<attribute>> filtering should give priority to a missing attribute #369 has a similar problem)

Resulting in:

Filter	Result
:hidehalfcovered:, :hidecovered:	UNCOVERED
:hideuncovered:, :hidecovered:	COVERED
:hideuncovered:, :hidehalfcovered:, :hidebyattribute: FAILED, PASSED	EXECUTED
:hideuncovered:, :hidehalfcovered:, :hidemissingattribute:, :hidebyattribute: PASSED	FAILED
:hideuncovered:, :hidehalfcovered:, :hidemissingattribute:, :hidebyattribute: FAILED	PASSED

Note: I went with subtractive filters so their absence would intuitively result in the full list, but perhaps additive showuncovered filters would have been more readable.

[JasperCraeghs]

Create a subgroup for every state, including intermediate ones
Display a subheader for each subgroup

How would you configure the names of the states, to use in the subheader?

---

Instead of adding a lot of new functionality and complexity to the item-matrix directive, I propose a new option for the item-piechart directive instead: :matrix: <<labels>>, with <<labels>> a comma-separated list of labels for which to generated a table, e.g. UNCOVERED,COVERED,EXECUTED,FAILED,PASSED.

This is more user-friendly and probably easier to implement and maintain.

[gcrabbe]

How would you configure the names of the states, to use in the subheader?

Good point. You'd need a label_set attribute as well.

---

Instead of adding a lot of new functionality and complexity to the item-matrix directive, I propose a new option for the item-piechart directive instead: :matrix: <<labels>>, with <<labels>> a comma-separated list of labels for which to generated a table, e.g. UNCOVERED,COVERED,EXECUTED,FAILED,PASSED.

As long as I can get the exact same table as my item-matrix as presently configured (with :targetcolumns: result and :splitintermediates:), it's fine by me.

Personally, I don't really see the point of having a matrix with fewer items than the associated pie chart, so I would appreciate if :matrix: with no <<labels>> defaulted to all of them.