acrn-hypervisor/doc/developer-guides/graphviz.rst

119 lines
3.1 KiB
ReStructuredText

.. _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 defining a finite-state machine
for pumping gas:
.. literalinclude:: images/gaspump.dot
.. graphviz:: images/gaspump.dot
:align: center