2.7.1. Block Diagram

sphinxcontrib-blockdiag is a Sphinx extension for embedding block diagrams. You can embed block diagrams with the .. blockdiag:: directive.

PyPI Package

https://pypi.org/project/sphinxcontrib-blockdiag/

Documentation

http://blockdiag.com/en/blockdiag/sphinxcontrib.html

Git Repository

https://github.com/blockdiag/sphinxcontrib-blockdiag

Sphinx extension for embedding block diagrams using blockdiag.

Features

  1. Generate block-diagram from dot like text (basic feature).

  2. Multilingualism for node-label (utf-8 only).

Todo

activate “Block Diagram” extension.

Directive Body Diagram

.. blockdiag::

For more details, see sphinxcontrib-blockdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
1
2
3
4
5
6
7
.. blockdiag::
   :align: center

   blockdiag {
       A -> B -> C;
            B -> D;
   }

:which gives:

   .. include:: blockdiag-directive-body-example.rsti

Description Table

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. blockdiag::
   :align: center
   :desctable:

   blockdiag {
       A -> B -> C;
       A [description = "browsers in each client"];
       B [description = "web server"];
       C [description = "database server"];
   }

:which gives:

   .. include:: blockdiag-description-table-example.rsti

Include Diagram

the example
1
2
3
4
.. blockdiag:: block.diag
   :caption: Style attributes to nodes and edges (Block Diagram example)
   :align: center
   :width: 640

:which gives:

   .. blockdiag:: block.diag
      :caption: Style attributes to nodes and edges (Block Diagram example)
      :align: center
      :width: 640
which needs

The example above comes from the original Sample diagrams web page and processed the following file content:

Listing 2.2 Block Diagram example file (block.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
blockdiag {
    // Set boder-style, backgroun-color and text-color to nodes.
    A [style = dotted];
    B [style = dashed];
    C [color = pink, style = "3,3,3,3,15,3"]; //dashed_array format style
    D [shape = circle, color = "#888888", textcolor="#FFFFFF"];

    // Set border-style and color to edges.
    A -> B [style = dotted];
    B -> C [style = dashed];
    C -> D [color = "red", style = "3,3,3,3,15,3"]; //dashed_array format style

    // Set numbered-badge to nodes.
    E [numbered = 99];

    // Set background image to nodes (and erase label).
    F [label = "", background = "https://github.com/sphinx-doc/sphinx/raw/master/doc/_static/sphinx.png"];
    G [label = "", background = "https://www.python.org/static/community_logos/python-logo-master-v3-TM.png"];
    H [icon = "https://github.com/blockdiag/blockdiag.com/raw/master/sources/en/_static/help-browser.png"];
    I [icon = "https://github.com/blockdiag/blockdiag.com/raw/master/sources/en/_static/internet-mail.png"];
    J [shape = actor]

    // Set arrow direction to edges.
    E -> F [dir = none, label = edge];
    F -> G [dir = forward];
    G -> H [dir = back];

    group {
        orientation = portrait;
        color = lightgray;
        H -> I [dir = both];
    }

    // Set width and height to nodes.
    K [width = 192]; // default value is 128
    L [shape = square, height = 64]; // default value is 40

    // Use thick line
    J -> K [thick]
    K -> L;
}