Skip to content

Latest commit

 

History

History
86 lines (61 loc) · 3.28 KB

dot_graphs.rst

File metadata and controls

86 lines (61 loc) · 3.28 KB
Raw

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"]
.. seealso::
    To obtain the dot executable from the Graphviz library, see
    `the library's downloads section <https://graphviz.org/download/>`_.

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:

.. doxygenpage:: dotgraphs
    :project: dot_graphs