Plugins » Plots and graphs

These plugin allow you to render plots, graphs or QR codes directly from data specified inline in the page source. Similarly to math rendering, the graphics is rendered to a SVG that’s embedded directly in the HTML markup.

Plots

For Pelican, download the m/plots.py file, put it including the m/ directory into one of your PLUGIN_PATHS and add m.plots package to your PLUGINS in pelicanconf.py. For the Python doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.plots']
M_PLOTS_FONT = 'Source Sans Pro'

This feature has no equivalent in the Doxygen theme.

Set M_PLOTS_FONT to a font that matches your CSS theme (it’s Source Sans Pro for builtin m.css themes), note that you need to have the font installed on your system, otherwise it will fall back to whatever system font it finds instead (for example DejaVu Sans) and the output won’t look as expected. In addition you need the Matplotlib library installed. Get it via pip or your distribution package manager:

pip3 install matplotlib

The plugin produces SVG plots that make use of the CSS plot styling.

Bar charts

Currently the only supported plot type is a horizontal bar chart, denoted by .. plot:: directive with :type: hbar:

.. plot:: Fastest animals
    :type: barh
    :labels:
        Cheetah
        Pronghorn
        Springbok
        Wildebeest
    :units: km/h
    :values: 109.4 88.5 88 80.5

The multi-line :labels: option contain value labels, one per line. You can specify unit label using :units:, particular values go into :values: separated by whitespace, there should me as many values as labels. Hovering over the bars will show the concrete value in a title.

It’s also optionally possible to add error bars using :error: and configure bar colors using :colors:. The colors correspond to m.css color classes and you can either use one color for all or one for each value, separated by whitespace. Bar chart height is calculated automatically based on amount of values, you can adjust the bar height using :bar-height:. Default value is 0.4. Similarly it’s possible to specify graph width using :plot-width:, the default 8 is tuned for a page-wide plot.

It’s possible to add an extra line of labels using :labels-extra:. Again, there should be as many entries as primary labels and values. To omit an extra label for a value, specify it as the reST comment ...

.. plot:: Runtime cost
    :type: barh
    :labels:
        Ours minimal
        Ours default
        3rd party
        Full setup
    :labels-extra:
        15 modules
        60 modules
        200 modules
        ..
    :units: µs
    :values: 15.09 84.98 197.13 934.27
    :errors: 0.74 3.65 9.45 25.66
    :colors: success info danger dim
    :bar-height: 0.6

Stacked values

It’s possible to stack several values on each other by providing a second (third, …) like for :values: (and :errors: as well). The values are added together — not overlapped — so e.g. showing values of 20 and 40 stacked together will result in the bar being 60 units long in total. Hovering over the stacked values will show magnitude of just given part, not the summed value.

The :colors: option works for these as well, either have each line a single value on each line to color each “slice” differently, or have one color per value like shown above.

.. plot:: Download size (*.js, *.wasm)
    :type: barh
    :labels:
        Sdl2Application
        Sdl2Application
        EmscriptenApplication
    :labels-extra:
        -s USE_SDL=2
        -s USE_SDL=1
        ..
    :units: kB
    :values:
        111.9 74.4 52.1
        731.2 226.3 226.0
    :colors:
        success
        info

(graph source: https://blog.magnum.graphics/announcements/new-emscripten-application-implementation/)

Graphs

For Pelican, download the m/dot.py file, put it including the m/ directory into one of your PLUGIN_PATHS and add m.dot package to your PLUGINS in pelicanconf.py. For the Python doc theme, it’s enough to just list it in PLUGINS.

PLUGINS += ['m.dot']
M_DOT_FONT = 'Source Sans Pro'
M_DOT_FONT_SIZE = 16.0

Set M_DOT_FONT and M_DOT_FONT_SIZE to a font that matches your CSS theme (it’s Source Sans Pro at 16px for builtin m.css themes), note that you need to have the font installed on your system, otherwise it will fall back to whatever system font it finds instead (for example DejaVu Sans) and the output won’t look as expected.

In case of Doxygen, this feature is builtin. Use the @dot and @dotfile commands. It’s possible to add extra CSS classes by placing @m_class in a paragraph before the actual graph block, see the Doxygen theme-specific commands for more information. Font name and size is controlled using the builtin DOT_FONTNAME and DOT_FONTSIZE options.

In addition you need the Graphviz library installed (version 2.40.1 at least). Get it via your distribution package manager, for example on Ubuntu:

sudo apt install graphviz

The plugin produces SVG graphs that make use of the CSS graph styling.

Directed graphs

The .. digraph:: directive uses the dot tool to produce directed graphs. The optional directive argument is graph title, contents is whatever you would put inside the digraph block. Use the :class: to specify a CSS color class for the whole graph, it’s also possible to color particular nodes and edges using the (currently undocumented) class attribute.

.. digraph:: Finite state machine

    rankdir=LR

    S₁ [shape=doublecircle class="m-primary"]
    S₂ [shape=circle]
    _  [style=invis]

    _  -> S₁ [class="m-warning"]
    S₁ -> S₂ [label="0"]
    S₂ -> S₁ [label="0"]
    S₁ -> S₁ [label="1"]
    S₂ -> S₂ [label="1"]

For more information check the official GraphViz Reference, in particular the extensive attribute documentation.

Note that currently all styling is discarded and only the class and fontsize attributes are taken into account.

Undirected graphs

The .. graph:: and .. strict-graph:: directives are similar to .. digraph::, but allow undirected graphs only. Again these are equivalent to graph and strict graph in the DOT language:

.. graph:: A house
    :class: m-success

    { rank=same 0 1 }
    { rank=same 2 4 }

    0 -- 1 -- 2 -- 3 -- 4 -- 0 -- 2 -- 4 --1
    3 [style=solid]

Graph figure

See the m.components plugin for details about graph figures using the .. graph-figure:: directive.

.. graph-figure:: Impenetrable logic

    .. digraph::

        rankdir=LR
        yes [shape=circle class="m-primary" style=filled]
        no [shape=circle class="m-primary"]
        yes -> no [label="no" class="m-primary"]
        no -> no [label="no"]

    No.

Impenetrable logic

No.

QR code

For Pelican, download the m/qr.py file, put it including the m/ directory into one of your PLUGIN_PATHS and add m.qr package to your PLUGINS in pelicanconf.py. For the Python doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.qr']

This feature has no equivalent in the Doxygen theme.

In addition you need the qrcode Python package installed. Get it via pip or your distribution package manager:

pip3 install qrcode

The QR code is rendered using the .. qr:: directive. Directive argument is the data to render. The library will auto-scale the image based on the input data size, you can override it using the optional :size: parameter. Resulting SVG has the .m-image class, meaning it’s centered and at most 100% of page width.

.. qr:: https://mcss.mosra.cz/plugins/plots-and-graphs/#qr-code
    :size: 256px