diff --git a/doc/howtos/process/graphviz.rst b/doc/howtos/process/graphviz.rst new file mode 100644 index 000000000..fe516808d --- /dev/null +++ b/doc/howtos/process/graphviz.rst @@ -0,0 +1,118 @@ +.. graphviz-examples: + +Drawings using graphviz +####################### + +We support using the Sphinx `graphviz extension`_ for creating simple +graphs and line drawings using the dot language. The advantage of using +graphviz for drawings is that source for a drawing is a text file that +can be edited and maintained in the repo along with the documentation. + +.. _graphviz extension: http://graphviz.gitlab.io + +These source ``.dot`` files are generally kept separate from the document itself, +and included by using a graphviz directive: + +.. code-block:: none + + .. graphviz:: images/boot-flow.dot + :name: boot-flow-example + :align: center + :caption: ACRN Hypervisor Boot Flow + +Where the boot-flow.dot file contains the drawing commands: + +.. literalinclude:: images/boot-flow.dot + +and the generated output would appear as this: + +.. graphviz:: images/boot-flow.dot + :name: boot-flow-example + :align: center + :caption: ACRN Hypervisor Boot Flow + + +Let's look at some more examples and then we'll get into more details +about the dot language and drawing options. + +Simple directed graph +********************* + +For simple drawings with shapes and lines, you can put the graphviz +commands in the content block for the directive. For example for a +simple directed graph (digraph) with two nodes connected by an arrow, +you can write: + + +.. code-block:: none + + .. graphviz:: + + digraph { + "a" -> "b" + } + +and get this: + +.. graphviz:: + + digraph { + "a" -> "b" + } + + +You can change the graph layout (from top-to-bottom to left-to-right), node +shapes (rectangles, circles, house, star, etc.), style (filled, rounded), +and colors, along with the text displayed in the node, and the resulting +image placement on the page (centered): + +.. literalinclude:: images/circle-square.dot + +.. graphviz:: images/circle-square.dot + :align: center + +You can use the `standard HTML color names`_ or use RGB values for +colors, as shown. + +.. _standard HTML color names: + https://www.w3schools.com/colors/colors_hex.asp + +Adding edge labels +****************** + +Here's an example of a drawing with labels on the edges (arrows) +between nodes. We also show how to change the default attributes for all +nodes and edges within this graph: + +.. literalinclude:: images/node-shape-edges.dot + +.. graphviz:: images/node-shape-edges.dot + :align: center + +Tables +****** + +For nodes with a ``record`` shape attribute, the text of the label is +presented in a table format: a vertical bar ``|`` starts a new row or +column and curly braces ``{ ... }`` specify a new row (if you're in a +column) or a new column (if you're in a row). For example: + +.. literalinclude:: images/record.dot + +.. graphviz:: images/record.dot + :align: center + +Note that you can also specify the horizontal alignment of text using escape +sequences ``\n``, ``\l`` and ``\r`` that divide the label into lines, centered, +left-justified, and right-justified, respectively. + +Finite-State Machine +******************** + +Here's an example of using graphviz for definine a finite-state machine +for pumping gas: + +.. literalinclude:: images/gaspump.dot + +.. graphviz:: images/gaspump.dot + :align: center diff --git a/doc/howtos/process/images/boot-flow.dot b/doc/howtos/process/images/boot-flow.dot new file mode 100644 index 000000000..d65c82a50 --- /dev/null +++ b/doc/howtos/process/images/boot-flow.dot @@ -0,0 +1,6 @@ +digraph G { + rankdir=LR; + bgcolor="transparent"; + UEFI -> "acrn.efi" -> "OS\nBootloader" -> + "SOS\nKernel" -> "ACRN\nDevice Model" -> "Virtual\nBootloader"; +} diff --git a/doc/howtos/process/images/circle-square.dot b/doc/howtos/process/images/circle-square.dot new file mode 100644 index 000000000..c81a2a3eb --- /dev/null +++ b/doc/howtos/process/images/circle-square.dot @@ -0,0 +1,9 @@ +digraph { + bgcolor="transparent"; rankdir=LR; + { a [shape=circle height="1" style=filled color=AntiqueWhite + label="Circle\nLabel"] + b [shape=box height="1" width="1" style="rounded,filled" + color="#F080F0" label="Square\nLabel"] + } + a -> b +} diff --git a/doc/howtos/process/images/gaspump.dot b/doc/howtos/process/images/gaspump.dot new file mode 100644 index 000000000..389823b01 --- /dev/null +++ b/doc/howtos/process/images/gaspump.dot @@ -0,0 +1,11 @@ +digraph gaspump { + rankdir=LR; + node [shape = circle;]; + edge [color = grey; fontsize=10]; + S0 -> S1 [ label = "Lift Nozzle" ] + S1 -> S0 [ label = "Replace Nozzle" ] + S1 -> S2 [ label = "Authorize Pump" ] + S2 -> S0 [ label = "Replace Nozzle" ] + S2 -> S3 [ label = "Pull Trigger" ] + S3 -> S2 [ label = "Release Trigger" ] +} diff --git a/doc/howtos/process/images/node-shape-edges.dot b/doc/howtos/process/images/node-shape-edges.dot new file mode 100644 index 000000000..ee59858aa --- /dev/null +++ b/doc/howtos/process/images/node-shape-edges.dot @@ -0,0 +1,8 @@ +digraph { + bgcolor=transparent; rankdir=LR; + node [shape="rectangle" style="filled" color="lightblue"] + edge [fontsize="12" fontcolor="grey"] + + "acrnprobe" -> "telemetrics-client" [label="crashlog\npath"] + "telemetrics-client" -> "backend" [label="log\ncontent"] +} diff --git a/doc/howtos/process/images/record.dot b/doc/howtos/process/images/record.dot new file mode 100644 index 000000000..35796d4b9 --- /dev/null +++ b/doc/howtos/process/images/record.dot @@ -0,0 +1,4 @@ +digraph { + a [shape=record label="left | {above|middle|below} | right"] + b [shape=record label="{row1\l|row2\r|{row3\nleft|row3\nright}|row4}"] +}