Using Dot Graphs

Sphinx graphviz prerequisites

To use Sphinx’s graphviz directive at all, the project documentation’s conf.py file must have sphinx.ext.graphviz added to the list of extensions.

extensions = ["breathe", "sphinx.ext.graphviz"]

See also

To obtain the dot executable from the Graphviz library, see the library’s downloads section.

Note

Typically, the dot executable’s path should be added to your system’s PATH environment variable. This is required for Sphinx, although the configuration option, graphviz_dot, can compensate for abnormal dot executable installations.

\dot and \dotfile commands

By default, breathe will translate any dot and dotfile commands into Sphinx graphviz directives. However, there are some caveats:

  1. The only graphviz option supported is the caption option. Graph captions are optionally specified using the dot or dotfile command syntax. All other graphviz directive options fallback to their default behavior.

    • any size hints from Doxygen’s dot or dotfile commands are ignored.

  2. Using Doxygen’s @ref command within any dot syntax is functionally ignored and treated as literal text.

Generated graphs from Doxygen

If Doxygen is configured to use the dot executable to generate certain graphs, then some of these graphs can be translated into Sphinx graphviz directives. Because this feature depends on having the dot executable installed to generate graphs in Sphinx, the option allow-dot-graphs must be specified for the following directives:

Attention

Only the following graphs generated by Doxygen can be found in its XML output:

graph relevance

configuration option

files included within

INCLUDE_GRAPH

files included by

INCLUDED_BY_GRAPH

inheritance

CLASS_GRAPH

collaboration

COLLABORATION_GRAPH

Unfortunately, the call and caller graphs are not provided by Doxygen’s XML output.

Examples of graphs generated by Doxygen are shown in this documentation’s Diagrams section of the doxygen test suite

Example Graphs

Graphs can be placed anywhere. For this example they are placed in a doxygen page.

.. doxygenpage:: dotgraphs
    :project: dot_graphs

This will render as:

page dotgraphs

Using @dot command

digraph G { bgcolor="purple:pink" label="a graph" fontcolor="white" subgraph cluster1 { fillcolor="blue:cyan" label="a cluster" fontcolor="white" style="filled" gradientangle="270" node [shape=box fillcolor="red:yellow" style="filled" gradientangle=90] "a node"; } }

basic graph elements

Using @dotfile command

Captions go here