Plugins » Plots and graphs

These plu­gin al­low you to render plots, graphs or QR codes dir­ectly from data spe­cified in­line in the page source. Sim­il­arly to math ren­der­ing, the graph­ics is rendered to a SVG that’s em­bed­ded dir­ectly in the HTML markup.

Plots

For Pel­ic­an, down­load the m/plots.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.plots pack­age to your PLUGINS in pelicanconf.py. For the Py­thon doc theme, it’s enough to just list it in PLUGINS:

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

This fea­ture has no equi­val­ent in the Doxy­gen theme.

Set M_PLOTS_FONT to a font that matches your CSS theme (it’s Source Sans Pro for built­in m.css themes), note that you need to have the font in­stalled on your sys­tem, oth­er­wise it will fall back to whatever sys­tem font it finds in­stead (for ex­ample De­jaVu Sans) and the out­put won’t look as ex­pec­ted. In ad­di­tion you need the Mat­plot­lib lib­rary in­stalled. Get it via pip or your dis­tri­bu­tion pack­age man­ager:

pip3 install matplotlib

The plu­gin pro­duces SVG plots that make use of the CSS plot styl­ing.

Bar charts

Cur­rently the only sup­por­ted plot type is a ho­ri­zont­al bar chart, de­noted by .. plot:: dir­ect­ive with :type: hbar:

.. plot:: Fastest animals
    :type: barh
    :labels:
        Cheetah
        Pronghorn
        Springbok
        Wildebeest
    :units: km/h
    :values: 109.4 88.5 88 80.5
109.4 km/h 88.5 km/h 88.0 km/h 80.5 km/h 0 20 40 60 80 100 km/h Cheetah Pronghorn Springbok Wildebeest Fastest animals

The multi-line :labels: op­tion con­tain value la­bels, one per line. You can spe­cify unit la­bel us­ing :units:, par­tic­u­lar val­ues go in­to :values: sep­ar­ated by whitespace, there should me as many val­ues as la­bels. Hov­er­ing over the bars will show the con­crete value in a title.

It’s also op­tion­ally pos­sible to add er­ror bars us­ing :error: and con­fig­ure bar col­ors us­ing :colors:. The col­ors cor­res­pond to m.css col­or classes and you can either use one col­or for all or one for each value, sep­ar­ated by whitespace. Bar chart height is cal­cu­lated auto­mat­ic­ally based on amount of val­ues, you can ad­just the bar height us­ing :bar-height:. De­fault value is 0.4. Sim­il­arly it’s pos­sible to spe­cify graph width us­ing :plot-width:, the de­fault 8 is tuned for a page-wide plot.

It’s pos­sible to add an ex­tra line of la­bels us­ing :labels-extra:. Again, there should be as many entries as primary la­bels and val­ues. To omit an ex­tra la­bel for a value, spe­cify it as the reST com­ment ...

.. 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
15.09 ± 0.74 µs 84.98 ± 3.65 µs 197.13 ± 9.45 µs 934.27 ± 25.66 µs 0 200 400 600 800 1000 µs Ours minimal Ours default 3rd party Full setup 15 modules 60 modules 200 modules Runtime cost

Stacked val­ues

It’s pos­sible to stack sev­er­al val­ues on each oth­er by provid­ing a second (third, …) like for :values: (and :errors: as well). The val­ues are ad­ded to­geth­er — not over­lapped — so e.g. show­ing val­ues of 20 and 40 stacked to­geth­er will res­ult in the bar be­ing 60 units long in total. Hov­er­ing over the stacked val­ues will show mag­nitude of just giv­en part, not the summed value.

The :colors: op­tion works for these as well, either have each line a single value on each line to col­or each “slice” dif­fer­ently, or have one col­or 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
111.9 kB 74.4 kB 52.1 kB 731.2 kB 226.3 kB 226.0 kB 0 100 200 300 400 500 600 700 800 kB Sdl2Application Sdl2Application EmscriptenApplication -s USE_SDL=2 -s USE_SDL=1 Download size (*.js, *.wasm)

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

Graphs

For Pel­ic­an, down­load the m/dot.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.dot pack­age to your PLUGINS in pelicanconf.py. For the Py­thon 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 built­in m.css themes), note that you need to have the font in­stalled on your sys­tem, oth­er­wise it will fall back to whatever sys­tem font it finds in­stead (for ex­ample De­jaVu Sans) and the out­put won’t look as ex­pec­ted.

In case of Doxy­gen, this fea­ture is built­in. Use the @dot and @dotfile com­mands. It’s pos­sible to add ex­tra CSS classes by pla­cing @m_class in a para­graph be­fore the ac­tu­al graph block, see the Doxy­gen theme-spe­cif­ic com­mands for more in­form­a­tion. Font name and size is con­trolled us­ing the built­in DOT_FONTNAME and DOT_FONTSIZE op­tions.

In ad­di­tion you need the Graphv­iz lib­rary in­stalled (ver­sion 2.40.1 at least). Get it via your dis­tri­bu­tion pack­age man­ager, for ex­ample on Ubuntu:

sudo apt install graphviz

The plu­gin pro­duces SVG graphs that make use of the CSS graph styl­ing.

Dir­ec­ted graphs

The .. digraph:: dir­ect­ive uses the dot tool to pro­duce dir­ec­ted graphs. The op­tion­al dir­ect­ive ar­gu­ment is graph title, con­tents is whatever you would put in­side the digraph block. Use the :class: to spe­cify a CSS col­or class for the whole graph, it’s also pos­sible to col­or par­tic­u­lar nodes and edges us­ing the (cur­rently un­doc­u­mented) class at­trib­ute.

.. 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"]
Finite state machine S₁ S₁ S₁->S₁ 1 S₂ S₂ S₁->S₂ 0 S₂->S₁ 0 S₂->S₂ 1 _->S₁

For more in­form­a­tion check the of­fi­cial GraphV­iz Ref­er­en­ce, in par­tic­u­lar the ex­tens­ive at­trib­ute doc­u­ment­a­tion.

Un­dir­ec­ted graphs

The .. graph:: and .. strict-graph:: dir­ect­ives are sim­il­ar to .. digraph::, but al­low un­dir­ec­ted graphs only. Again these are equi­val­ent to graph and strict graph in the DOT lan­guage:

.. 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]
A house 0 0 1 1 0--1 2 2 0--2 1--2 4 4 2--4 3 3 2--3 4--0 4--1 3--4

Graph fig­ure

See the m.com­pon­ents plu­gin for de­tails about graph fig­ures us­ing the .. graph-figure:: dir­ect­ive.

.. 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.
yes yes no no yes->no no no->no no
Im­pen­et­rable lo­gic

No.

QR code

For Pel­ic­an, down­load the m/qr.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.qr pack­age to your PLUGINS in pelicanconf.py. For the Py­thon doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.qr']

This fea­ture has no equi­val­ent in the Doxy­gen theme.

In ad­di­tion you need the qr­code Py­thon pack­age in­stalled. Get it via pip or your dis­tri­bu­tion pack­age man­ager:

pip3 install qrcode

The QR code is rendered us­ing the .. qr:: dir­ect­ive. Dir­ect­ive ar­gu­ment is the data to render. The lib­rary will auto-scale the im­age based on the in­put data size, you can over­ride it us­ing the op­tion­al :size: para­met­er. Res­ult­ing SVG has the .m-image class, mean­ing it’s centered and at most 100% of page width.

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