119 lines
3.1 KiB
ReStructuredText
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
|