Installing blockdiag on OS X is fairly straight forward. A couple pip commands later and you’ll be done.
Note: If you are running python in a virtualenv, don’t forget to activate it
before installing your pip modules or they’ll be installed globally (my shell
prompt changes to include a (pelican) in it when I’m inside the
virtualenv.
Installing blockdiag modules
1(pelican)[louisk@iPwn cryptomonkeys.com ]$ pip install blockdiag nwdiag blockdiagcontrib-eps blockdiagcontrib-excelhogan blockdiagcontrib-cisco seqdiag blockdiagcontrib-square blockdiagcontrib-tex blockdiagcontrib-labeledbox blockdiagcontrib-class blockdiagcontrib-excelshape blockdiagcontrib-math
2Collecting blockdiag
3 Downloading blockdiag-1.5.3-py2.py3-none-any.whl (2.7MB)
4 100% |████████████████████████████████| 2.7MB 45kB/s
5Collecting nwdiag
6 Downloading nwdiag-1.0.4-py2.py3-none-any.whl (7.7MB)
7 100% |████████████████████████████████| 7.7MB 26kB/s
8Collecting blockdiagcontrib-eps
9 Downloading blockdiagcontrib_eps-0.1.1-py2.py3-none-any.whl
10Collecting blockdiagcontrib-excelhogan
11 Downloading blockdiagcontrib-excelhogan-0.1.0.tar.gz
12Collecting blockdiagcontrib-cisco
13 Downloading blockdiagcontrib-cisco-0.1.8.tar.gz (5.8MB)
14 100% |████████████████████████████████| 5.8MB 21kB/s
15Collecting seqdiag
16 Downloading seqdiag-0.9.5-py2.py3-none-any.whl (2.6MB)
17 100% |████████████████████████████████| 2.6MB 39kB/s
18Collecting blockdiagcontrib-square
19 Downloading blockdiagcontrib-square-0.1.3.tar.gz
20Collecting blockdiagcontrib-tex
21 Downloading blockdiagcontrib-tex-0.2.2.tar.gz
22Collecting blockdiagcontrib-labeledbox
23 Downloading blockdiagcontrib-labeledbox-0.1.1.tar.gz
24Collecting blockdiagcontrib-class
25 Downloading blockdiagcontrib-class-0.1.3.tar.gz
26Collecting blockdiagcontrib-excelshape
27 Downloading blockdiagcontrib-excelshape-0.1.0.zip
28Collecting blockdiagcontrib-math
29 Downloading blockdiagcontrib_math-0.9.0-py2.py3-none-any.whl
30Collecting webcolors (from blockdiag)
31 Downloading webcolors-1.5.tar.gz
32Requirement already satisfied (use --upgrade to upgrade): setuptools in /Users/louisk/ownCloud/documents/Work/Cryptomonkeys/pelican/lib/python3.4/site-packages (from blockdiag)
33Collecting funcparserlib (from blockdiag)
34 Downloading funcparserlib-0.3.6.tar.gz
35Requirement already satisfied (use --upgrade to upgrade): Pillow in /Users/louisk/ownCloud/documents/Work/Cryptomonkeys/pelican/lib/python3.4/site-packages (from blockdiag)
36Collecting openpyxl (from blockdiagcontrib-excelhogan)
37 Downloading openpyxl-2.2.5.tar.gz (108kB)
38 100% |████████████████████████████████| 110kB 65kB/s
39Collecting jdcal (from openpyxl->blockdiagcontrib-excelhogan)
40 Downloading jdcal-1.0.tar.gz
41Building wheels for collected packages: blockdiagcontrib-excelhogan, blockdiagcontrib-cisco, blockdiagcontrib-square, blockdiagcontrib-tex, blockdiagcontrib-labeledbox, blockdiagcontrib-class, blockdiagcontrib-excelshape, webcolors, funcparserlib, openpyxl, jdcal
42 Running setup.py bdist_wheel for blockdiagcontrib-excelhogan
43 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/15/8b/27/9e1f5a5d71d160e3e461cf1199cfdc080c6ebe83c60654beaa
44 Running setup.py bdist_wheel for blockdiagcontrib-cisco
45 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/db/d6/f2/ebc6ca11fca82898b1d80761b288329e876eab32f34bcd6d12
46 Running setup.py bdist_wheel for blockdiagcontrib-square
47 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/1f/07/ea/794a37b8275359269d4ae8e69107e1d6e7c166a3dcd567c635
48 Running setup.py bdist_wheel for blockdiagcontrib-tex
49 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/88/ad/cb/8f9603c32ecdee6a8235a1f8e8e9c8ca0c9cefc68290e2fb8d
50 Running setup.py bdist_wheel for blockdiagcontrib-labeledbox
51 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/95/1d/6d/0a7c4bcc134b70e43709c6af6b022d807d311686709f756a7a
52 Running setup.py bdist_wheel for blockdiagcontrib-class
53 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/71/7c/3e/b1d791f52c4fd973b6a9549c5cb7c2eea5fb7399597f87b767
54 Running setup.py bdist_wheel for blockdiagcontrib-excelshape
55 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/1d/9b/54/d8f1979266dc30c10e36f833f26fc31daf6905a90e1ea815fa
56 Running setup.py bdist_wheel for webcolors
57 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/0a/9b/89/83fb075ab22d93e6525de4a6b29fa42e2a49f070a19e0dcd3a
58 Running setup.py bdist_wheel for funcparserlib
59 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/1d/4f/13/694848fa3a4ca3d7080c606603dc8f92d26d55c8c0abb1fe9d
60 Running setup.py bdist_wheel for openpyxl
61 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/ff/19/0c/642824e09ffb56bea48aa77b6f00f220a3b42125124eb4f726
62 Running setup.py bdist_wheel for jdcal
63 Stored in directory: /Users/louisk/Library/Caches/pip/wheels/91/14/40/9578071e3df07cbbbdce9002ca8c5de065c74c4f840c264d86
64Successfully built blockdiagcontrib-excelhogan blockdiagcontrib-cisco blockdiagcontrib-square blockdiagcontrib-tex blockdiagcontrib-labeledbox blockdiagcontrib-class blockdiagcontrib-excelshape webcolors funcparserlib openpyxl jdcal
65Installing collected packages: webcolors, funcparserlib, blockdiag, nwdiag, blockdiagcontrib-eps, jdcal, openpyxl, blockdiagcontrib-excelhogan, blockdiagcontrib-cisco, seqdiag, blockdiagcontrib-square, blockdiagcontrib-tex, blockdiagcontrib-labeledbox, blockdiagcontrib-class, blockdiagcontrib-excelshape, blockdiagcontrib-math
66Successfully installed blockdiag-1.5.3 blockdiagcontrib-cisco-0.1.8 blockdiagcontrib-class-0.1.3 blockdiagcontrib-eps-0.1.1 blockdiagcontrib-excelhogan-0.1.0 blockdiagcontrib-excelshape-0.1.0 blockdiagcontrib-labeledbox-0.1.1 blockdiagcontrib-math-0.9.0 blockdiagcontrib-square-0.1.3 blockdiagcontrib-tex-0.2.2 funcparserlib-0.3.6 jdcal-1.0 nwdiag-1.0.4 openpyxl-2.2.5 seqdiag-0.9.5 webcolors-1.5
67(pelican)[louisk@iPwn cryptomonkeys.com ]$
Testing out blockdiag
Here are the edits for your pelicanconf.py:
1PLUGINS = [ ... 'liquid_tags.graphviz', 'liquid_tags.b64img', 'liquid_tags.diag' ]
Both the graphviz and diag sub modules of Liquid_Tags produce base64 images inline, which is why we need to also include the b64img sub module.
Now that we have things setup, we should be able to insert code like this into our markdown documents and have it rendered into an image on the fly.
Graphviz
1{% graphviz
2 dot {
3 digraph G {
4 main -> parse -> execute;
5 main -> init;
6 main -> cleanup;
7 execute -> make_string;
8 execute -> printf
9 init -> make_string;
10 main -> printf;
11 execute -> compare;
12 }
13 }
14%}
If everything is working properly, this should render as the following graphic:
{% graphviz dot { digraph G { main -> parse -> execute; main -> init; main -> cleanup; execute -> make_string; execute -> printf init -> make_string; main -> printf; execute -> compare; } } %}
Graphviz documentation is available here
Blockdiag
Moving on to Blockdiag. Lets start with a simple example:
1{% blockdiag
2 blockdiag {
3 A -> B -> C;
4 B -> D;
5 }
6%}
If everything works properly, we should end up with a graphic here:
{% blockdiag blockdiag { A -> B -> C; B -> D; } %}
We’ve intentionally started out very simple. It can get complicated quickly. Blockdiag documentation is available here . Blockdiag also offers other kinds of diagrams including Sequence Diagrams, Network Diagrams, and even Packet Diagrams. I’ll show some simple examples of each.
Sequence diagram
1{% blockdiag
2 seqdiag {
3 A -> B -> C;
4 B -> D;
5 }
6%}
{% blockdiag seqdiag { A -> B -> C; B -> D; } %}
Network Diagram
1{% blockdiag
2 nwdiag {
3 network dmz {
4 web01;
5 web02;
6 stg01;
7 }
8
9 network internal {
10 web01;
11 web02;
12 db01;
13 db02;
14 }
15 }
16%}
{% blockdiag nwdiag { network dmz { web01; web02; stg01; }
network internal {
web01;
web02;
db01;
db02;
}
}
%}
Packet Diagram
1{% blockdiag
2 packetdiag {
3 0-7: Source Port
4 8-15: Destination Port
5 16-31: Sequence Number
6 32-47: Acknowledgment Number
7 }
8%}
{% blockdiag packetdiag { 0-7: Source Port 8-15: Destination Port 16-31: Sequence Number 32-47: Acknowledgment Number } %}
Rack Diagram
1{% blockdiag
2 rackdiag {
3 24U;
4
5 1: UPS [3U, 0.5A, 10kg];
6 5: Disk Array [2U, 0.5A];
7 7: DB Master
8 8: DB Mirror (1)
9 9: DB Mirror (2)
10 11: Web Server (1)
11 11: Web Server (2)
12 12: Web Server (3)
13 12: Web Server (4)
14 14: LoadBalancer
15 }
16%}
{% blockdiag rackdiag { 24U;
1: UPS [3U, 0.5A, 10kg];
5: Disk Array [2U, 0.5A];
7: DB Master
8: DB Mirror (1)
9: DB Mirror (2)
11: Web Server (1)
11: Web Server (2)
12: Web Server (3)
12: Web Server (4)
14: LoadBalancer
}
%}
Summary
From here, you can diagram most anything you need. The best part, you can version all of this since its plain text. Now its easy to keep diagrams current, reflecting reality, and you can even automate the creation of diagrams, since they’re just text.
Comments