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.

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¶

Use :xlabels: to set labels for columns of the data.

Use :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¶

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.
Use :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