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

../_images/need_bar_8dc6a.svg

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:

Full bar chart
.. 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

Title example

It is possible to create bar charts without title.

Example

.. needbar::

   5,20,15
   10,15,10
   15,10,20
   20,15,10

Result

../_images/need_bar_27603.svg

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

A more real bar chart

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

Legend example

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

Axis title example

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

Labels example 1Labels example 2

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

stacked example

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_sum example 1show_sum example 2

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

show_top_sum example 1show_top_sum example 2

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

horizontal example 1horizontal example 2

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

transpose example 1transpose example 2

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

rotation example

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

separator example

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

colors example

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

text_color example

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

style example