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