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.
By default, breathe will translate any dot and dotfile commands into Sphinx graphviz directives. However, there are some caveats:
- 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. - Using Doxygen's
@ref
command within any dot syntax is functionally ignored and treated as literal text.
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:
- :ref:`doxygenclass`
- :ref:`doxygenstruct`
- :ref:`doxygenfile`
- :ref:`doxygenindex`
- :ref:`autodoxygenfile`
- :ref:`autodoxygenindex`
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
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