Skip to content

Commit 467e65a

Browse files
dbkinderdbkinder
committed
doc: add some docs about graphviz for drawings
Add some practical examples and pointers to additional information about using graphviz. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
1 parent 4d62c56 commit 467e65a

File tree

6 files changed

+156
-0
lines changed

6 files changed

+156
-0
lines changed

‎doc/howtos/process/graphviz.rst

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
.. graphviz-examples:
2+
3+
Drawings using graphviz
4+
#######################
5+
6+
We support using the Sphinx `graphviz extension`_ for creating simple
7+
graphs and line drawings using the dot language. The advantage of using
8+
graphviz for drawings is that source for a drawing is a text file that
9+
can be edited and maintained in the repo along with the documentation.
10+
11+
.. _graphviz extension: http://graphviz.gitlab.io
12+
13+
These source ``.dot`` files are generally kept separate from the document itself,
14+
and included by using a graphviz directive:
15+
16+
.. code-block:: none
17+
18+
.. graphviz:: images/boot-flow.dot
19+
:name: boot-flow-example
20+
:align: center
21+
:caption: ACRN Hypervisor Boot Flow
22+
23+
Where the boot-flow.dot file contains the drawing commands:
24+
25+
.. literalinclude:: images/boot-flow.dot
26+
27+
and the generated output would appear as this:
28+
29+
.. graphviz:: images/boot-flow.dot
30+
:name: boot-flow-example
31+
:align: center
32+
:caption: ACRN Hypervisor Boot Flow
33+
34+
35+
Let's look at some more examples and then we'll get into more details
36+
about the dot language and drawing options.
37+
38+
Simple directed graph
39+
*********************
40+
41+
For simple drawings with shapes and lines, you can put the graphviz
42+
commands in the content block for the directive. For example for a
43+
simple directed graph (digraph) with two nodes connected by an arrow,
44+
you can write:
45+
46+
47+
.. code-block:: none
48+
49+
.. graphviz::
50+
51+
digraph {
52+
"a" -> "b"
53+
}
54+
55+
and get this:
56+
57+
.. graphviz::
58+
59+
digraph {
60+
"a" -> "b"
61+
}
62+
63+
64+
You can change the graph layout (from top-to-bottom to left-to-right), node
65+
shapes (rectangles, circles, house, star, etc.), style (filled, rounded),
66+
and colors, along with the text displayed in the node, and the resulting
67+
image placement on the page (centered):
68+
69+
.. literalinclude:: images/circle-square.dot
70+
71+
.. graphviz:: images/circle-square.dot
72+
:align: center
73+
74+
You can use the `standard HTML color names`_ or use RGB values for
75+
colors, as shown.
76+
77+
.. _standard HTML color names:
78+
https://www.w3schools.com/colors/colors_hex.asp
79+
80+
Adding edge labels
81+
******************
82+
83+
Here's an example of a drawing with labels on the edges (arrows)
84+
between nodes. We also show how to change the default attributes for all
85+
nodes and edges within this graph:
86+
87+
.. literalinclude:: images/node-shape-edges.dot
88+
89+
.. graphviz:: images/node-shape-edges.dot
90+
:align: center
91+
92+
Tables
93+
******
94+
95+
For nodes with a ``record`` shape attribute, the text of the label is
96+
presented in a table format: a vertical bar ``|`` starts a new row or
97+
column and curly braces ``{ ... }`` specify a new row (if you're in a
98+
column) or a new column (if you're in a row). For example:
99+
100+
.. literalinclude:: images/record.dot
101+
102+
.. graphviz:: images/record.dot
103+
:align: center
104+
105+
Note that you can also specify the horizontal alignment of text using escape
106+
sequences ``\n``, ``\l`` and ``\r`` that divide the label into lines, centered,
107+
left-justified, and right-justified, respectively.
108+
109+
Finite-State Machine
110+
********************
111+
112+
Here's an example of using graphviz for definine a finite-state machine
113+
for pumping gas:
114+
115+
.. literalinclude:: images/gaspump.dot
116+
117+
.. graphviz:: images/gaspump.dot
118+
:align: center

‎doc/howtos/process/images/boot-flow.dot

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
digraph G {
2+
rankdir=LR;
3+
bgcolor="transparent";
4+
UEFI -> "acrn.efi" -> "OS\nBootloader" ->
5+
"SOS\nKernel" -> "ACRN\nDevice Model" -> "Virtual\nBootloader";
6+
}

‎doc/howtos/process/images/circle-square.dot

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
digraph {
2+
bgcolor="transparent"; rankdir=LR;
3+
{ a [shape=circle height="1" style=filled color=AntiqueWhite
4+
label="Circle\nLabel"]
5+
b [shape=box height="1" width="1" style="rounded,filled"
6+
color="#F080F0" label="Square\nLabel"]
7+
}
8+
a -> b
9+
}

‎doc/howtos/process/images/gaspump.dot

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
digraph gaspump {
2+
rankdir=LR;
3+
node [shape = circle;];
4+
edge [color = grey; fontsize=10];
5+
S0 -> S1 [ label = "Lift Nozzle" ]
6+
S1 -> S0 [ label = "Replace Nozzle" ]
7+
S1 -> S2 [ label = "Authorize Pump" ]
8+
S2 -> S0 [ label = "Replace Nozzle" ]
9+
S2 -> S3 [ label = "Pull Trigger" ]
10+
S3 -> S2 [ label = "Release Trigger" ]
11+
}

‎doc/howtos/process/images/node-shape-edges.dot

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
digraph {
2+
bgcolor=transparent; rankdir=LR;
3+
node [shape="rectangle" style="filled" color="lightblue"]
4+
edge [fontsize="12" fontcolor="grey"]
5+
6+
"acrnprobe" -> "telemetrics-client" [label="crashlog\npath"]
7+
"telemetrics-client" -> "backend" [label="log\ncontent"]
8+
}

‎doc/howtos/process/images/record.dot

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
digraph {
2+
a [shape=record label="left | {above|middle|below} | <f1>right"]
3+
b [shape=record label="{row1\l|row2\r|{row3\nleft|<f2>row3\nright}|row4}"]
4+
}

0 commit comments

Comments
 (0)