needbar¶
New in version 0.7.5.
needbar
adds a bar-chart to your documentation:
Example
.. needbar::
5,20,15
10,15,10
15,10,20
20,15,10
Result
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.
Note
This generates multiple image files per needbar
and allows
the document engine to pick the appropriate image type (vector or raster).
Options¶
Example with all options used:
.. needbar:: 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_top_sum:
:show_sum:
:sum_rotation: 90
:transpose:
:horizontal:
Z; 5;20;15
Y;10;15;10
X;15;10;20
W;20;15;10
title¶
You can specify the headline of the bar chart using the title
argument.
Example
.. needbar:: Title example
5,20,15
10,15,10
15,10,20
20,15,10
Result
It is possible to create bar charts without title.
Example
.. needbar::
5,20,15
10,15,10
15,10,20
20,15,10
Result
content¶
In the example below, we fetch the :xlabels:
and :ylabels:
options from the content using FROM_DATA
with the labels.
You can use white spaces to format the table to improve readability.
From the content, we interpret each value either as a static float/int value or as a Filter string. We get the bar chart’s data (values) from the amount of need objects found by the filter string.
Below is a more realistic example with data fetched from filters, together with hardcoded data:
Example
.. 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
Result
legend¶
You can place a legend on the barchart by setting the :legend:
flag.
The :legend:
flag does not support any values.
Example
.. needbar:: Legend example
:legend:
5,20,15
10,15,10
15,10,20
20,15,10
Result
axis title¶
You can enable axis titles on the barchart by setting the :x_axis_title:
or :y_axis_title:
options.
Hint
If you use horizontal or transpose, the meaning of :x_axis_title:
and :y_axis_title:
must be understandable.
So you have to change the description accordingly.
Example
.. needbar:: Axis title example
:x_axis_title: types
:y_axis_title: numbers
5,20,15
10,15,10
15,10,20
20,15,10
Result
labels¶
:xlabels:
to set labels for columns of the data.:ylabels:
to set labels for row of the data.You can define the :xlabels:
and/or :ylabels:
by setting a comma separated string.
The amount of labels must match the amount of values/lines from content.
Also, you can set the :xlabels:
and/or :ylabels:
value to FROM_DATA
to fetch the labels from the content.
Hint
In a normal bar chart, we use the :xlabels:
as the labels of the x-axis on the chart and the :ylabels:
as the labels of legend.
But if you use horizontal or transpose, the meaning of :x_axis_title:
and :y_axis_title:
will change automatically.
Example
.. 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
Result
stacked¶
You can render the barchart in a stacked design by setting :stacked:
flag.
The :stacked:
flag does not support any values.
Example
.. needbar:: stacked example
:stacked:
5,20,15
10,15,10
15,10,20
20,15,10
Result
show_sum¶
You can render the barchart with detailed information of the height of each bar by setting the :show_sum:
flag.
The :show_sum:
flag does not support any values and it’s useful with the stacked
option enabled.
Example
.. 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
Result
show_top_sum¶
You can render the barchart with detailed information of the height of each bar above by setting the :show_top_sum:
flag.
The :show_sum:
flag does not support any values and it’s useful with the stacked
option enabled.
Example
.. needbar:: show_top_sum example 1
:show_top_sum:
5,20,15
10,15,10
15,10,20
20,15,10
.. needbar:: show_top_sum example 2
:stacked:
:show_sum:
:show_top_sum:
5,20,15
10,15,10
15,10,20
20,15,10
Result
horizontal¶
You can render the bar chart with horizontal bars by setting the :horizontal:
flag.
The :horizontal:
flag does not support any values and it’s useful with the stacked
option enabled.
Hint
The meaning of labels will change automatically with the usage of :horizontal:
. We will use the
:x_axis_title:
as labels for the y-axis and use the :y_axis_title:
as the values in the legend.
Example
.. 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
Result
transpose¶
You can transpose the data in the content by setting the :transpose:
flag.
The idea is, you can try to see the data from different point of view, without refactoring.
The :transpose:
flag does not support any values and it’s useful with big content tables.
Hint
Using the
:transpose:
flag, transposes the:x_axis_title:
and:y_axis_title:
fetched from the content data or specified with labels but does not transpose the extra axis title.Remember that with the
:transpose:
flag, the length and height of the content data changes, not to think about the width of matching elements, like colors. Please review the impact of:transpose:
before using it.
Example
.. 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
Result
rotation¶
:xlabels_rotation:
to set rotation of labels for x-axis on the diagram.:ylabels_rotation:
to set rotation of labels for y-axis on the diagram.:sum_rotation:
to set rotation of labels for bars on the diagram.Example
.. needbar:: rotation example
:legend:
:xlabels: a, b, c
:xlabels_rotation: 90
:ylabels: Z, Y, X, W
:ylabels_rotation: 40
:show_top_sum:
:show_sum:
:sum_rotation: 90
5,20,15
10,15,10
15,10,20
20,15,10
Result
separator¶
You can specify a custom separator between the values in the content by setting the :separator:
flag.
This ensures the use of ,
(the default separator) in a filter rule. Other options will be processed as defined there.
The :separator:
is a string that supports any symbols.
Example
.. needbar:: separator example
:separator: -
5-20-15
10-15-10
15-10-20
20-15-10
Result
colors¶
: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 besides names, :colors:
options also supports hex-values like #ffcc00
.
Hint
In a normal bar chart, we use the :colors:
for the legend and bars itself.
When you use horizontal or transpose, the bar’s length must be equal to :xlabels:
or :ylabels:
.
If the length does not fit, it will fill the bar with the colors again and you will get a warning.
Example
.. 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
Result
text_color¶
:text_color:
defines the color for text inside the bar chart and the labels.
Example
.. 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
Result
style¶
: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
Example
.. 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
Result