.. needbar::
5,20,15
10,15,10
15,10,20
20,15,10
Options
Example with all options used:
.. needbar:: My full bar chart
:legend:
:colors: #ffcc88, #ffcc00, #444444
:text_color: crimson
:style: dark_background
:x_axis_title: x_axis_title
:xlabels_rotation: 90
:xlabels: a, b, c
:y_axis_title: y_axis_title
:ylabels: FROM_DATA
:ylabels_rotation: 45
:separator: ;
:stacked:
:show_sum:
:transpose:
:horizontal:
Z; 5;20;15
Y;10;15;10
X;15;10;20
W;20;15;10
If a title is given, it will be used as a headline in the bar chart.
.. needbar:: Title example
5,20,15
10,15,10
15,10,20
20,15,10
It is even possible to create bar charts without title.
.. needbar::
5,20,15
10,15,10
15,10,20
20,15,10
Here we are using FROM_DATA with the labels to fetch the xlabels and ylabels from the content.
It is possible to use white spaces to format the table to be easily readed.
Each content value gets interpreted either as static float/int value or as a Filter string.
The amount of found needs by the filter string is then used as value.
This is a more realistic example with data fetched from filters, together with hard coded data:
.. needbar:: A more real bar chart
:legend:
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, open , in progress , closed , done , implemented , number
Requirement, type=='req' and status=='open', type=='req' and status=='in progress', type=='req' and status=='closed', type=='req' and status=='done', type=='req' and status=='implemented', 5
Test, type=='test' and status=='open',type=='test' and status=='in progress',type=='test' and status=='closed',type=='test' and status=='done',type=='test' and status=='implemented', 7
Specification, type=='spec' and status=='open',type=='spec' and status=='in progress',type=='spec' and status=='closed',type=='spec' and status=='done',type=='spec' and status=='implemented', 9
If :legend: is given, a legend will be placed in the bar chart.
:legend: is a flag and does not support any values.
.. needbar:: Legend example
:legend:
5,20,15
10,15,10
15,10,20
20,15,10
If titles are given via :x_axis_title: or :y_axis_title:, the axis get titles placed in the bar chart.
Hint
If you use horizontal or transpose, the meaning of :x_axis_title: and :y_axis_title: still have to old meaning.
So you have to change the description accordingly.
.. needbar:: Legend example
:x_axis_title: types
:y_axis_title: numbers
5,20,15
10,15,10
15,10,20
20,15,10
Use :xlabels: to set labels for columns of the data.
Use :ylabels: to set labels for row of the data.
:xlabels: and/or :xlabels: must get a comma separated string and the amount of labels must match the amount of
values/lines from content. It is even possible to use FROM_DATA as string to fetch the labels from the content
Hint
In a normal bar chart, the :xlabels: are used for the labels of the x-axis on the chart.
The :ylabels: are used for the labels of legend.
But if you use horizontal or transpose, the meaning of :x_axis_title: and :y_axis_title: will automatically be changed.
.. needbar:: Labels example 1
:legend:
:xlabels: a, b, c
:ylabels: Z, Y, X, W
5,20,15
10,15,10
15,10,20
20,15,10
.. needbar:: Labels example 2
:legend:
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, a, b, c
Z, 5,20,15
Y,10,15,10
X,15,10,20
W,20,15,10
If :stacked: is given, the bar chart will be rendered in a stacked design.
:stacked: is a flag and does not support any values.
.. needbar:: stacked example
:stacked:
5,20,15
10,15,10
15,10,20
20,15,10
If :show_sum: is given, the bar chart will be rendered with detailed information of the height of each bar.
Especially useful in stacked option.
:show_sum: is a flag and does not support any values.
.. needbar:: show_sum example 1
:show_sum:
5,20,15
10,15,10
15,10,20
20,15,10
.. needbar:: show_sum example 2
:stacked:
:show_sum:
5,20,15
10,15,10
15,10,20
20,15,10
If :horizontal: is given, the bar chart will be rendered with horizontal bars.
:horizontal: is a flag and does not support any values.
Hint
The meaning of labels will be automatically change with the usage of :horizontal:.
:x_axis_title: or is now been used as labels for the y axis. :y_axis_title: is still the values in the legend.
.. needbar:: horizontal example 1
:horizontal:
5,20,15
10,15,10
15,10,20
20,15,10
.. needbar:: horizontal example 2
:stacked:
:legend:
:show_sum:
:horizontal:
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, a, b, c
Z, 5,20,15
Y,10,15,10
X,15,10,20
W,20,15,10
If :transpose: is given, the data in the content are transposed.
The idea is, you can try to see the data from different point of view, without refactoring.
Especially helpful with big content tables.
:transpose: is a flag and does not support any values.
Hint
:x_axis_title: and :y_axis_title: fetched from the content data or specified with labels are transposed, too.
But extra given axis title not.
Please remember with transpose the length and height of the content data get changed,
so think even about the length of matching elements, like colors.
So please review the impact of :transpose:.
.. needbar:: transpose example 1
:transpose:
5,20,15
10,15,10
15,10,20
20,15,10
.. needbar:: transpose example 2
:legend:
:stacked:
:show_sum:
:transpose:
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, a, b, c
Z, 5,20,15
Y,10,15,10
X,15,10,20
W,20,15,10
Use :xlabels_rotation: to set rotation of labels for x-axis on the diagram.
Use :ylabels_rotation: to set rotation of labels for y-axis on the diagram.
.. needbar:: rotation example
:legend:
:xlabels: a, b, c
:xlabels_rotation: 90
:ylabels: Z, Y, X, W
:ylabels_rotation: 40
5,20,15
10,15,10
15,10,20
20,15,10
With :separator: a customized separator between the values in the data of the content can be specified.
Idea is to overcome possible use of , in a filter rule.
Other options will be processed as defined there.
:separator: is a string and support any symbols.
.. needbar:: separator example
:separator: ;
5;20;15
10;15;10
15;10;20
20;15;10
:colors: takes a comma separated list of color names and uses them for the bar charts.
See Matplotlib documentation of supported colors
for a complete list of color names.
But beside names also hex-values like #ffcc00 are supported.
Hint
In a normal bar chart, the :colors: are used for the legend and bars itself.
So depending on horizontal or transpose, the length have to be same to :xlabels: or :ylabels:.
If the length does not fit, it will be filled with the colors again and you will get a warning.
.. needbar:: colors example
:legend:
:colors: lightcoral, gold, #555555, #888888
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, a, b, c
Z, 5,20,15
Y,10,15,10
X,15,10,20
W,20,15,10
:text_color: defines the color for text inside the bar chart and the labels.
.. needbar:: text_color example
:legend:
text_color: green
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, a, b, c
Z, 5,20,15
Y,10,15,10
X,15,10,20
W,20,15,10
:style: activates a complete style (colors, font, sizes) for a bar chart.
It takes a string, which must match the
supported Matplotlib style names.
Useful styles are for example:
default
classic
Solarize_Light2
dark_background
grayscale
.. needbar:: style example
:legend:
:style: Solarize_Light2
:xlabels: FROM_DATA
:ylabels: FROM_DATA
, a, b, c
Z, 5,20,15
Y,10,15,10
X,15,10,20
W,20,15,10
