124 lines
3.1 KiB
ReStructuredText
124 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 the 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:
|
|
|
|
.. 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 drawing:
|
|
|
|
.. graphviz::
|
|
|
|
digraph {
|
|
"a" -> "b"
|
|
}
|
|
|
|
|
|
You can change the following attributes:
|
|
|
|
* Graph layout (from top-to-bottom to left-to-right)
|
|
* Node shapes (rectangles, circles, houses, stars, etc.)
|
|
* Style (filled, rounded)
|
|
* Colors
|
|
* Text displayed in the node
|
|
* Placement of the resulting image on the page (centered)
|
|
|
|
Example:
|
|
|
|
.. 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``, which divide the label into lines that
|
|
are 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
|