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).

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
blockdiag A B C D

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
blockdiag A B C

Name

Description

A

browsers in each client

B

web server

C

database server

Include Diagram

the example
1
2
3
4
.. blockdiag:: blockdiag/example.diag
   :caption: Style attributes to nodes and edges (Block Diagram example)
   :align: center
   :width: 480
which gives
blockdiag A B C D E 99 H I J K L edge

Figure 2.46 Style attributes to nodes and edges (Block Diagram example)

which needs

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

Listing 2.5 Block Diagram example file (blockdiag/example.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;
}