Using Dot Graphs
================

.. _graphviz: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html#module-sphinx.ext.graphviz
.. _dot: https://www.doxygen.nl/manual/commands.html#cmddot
.. _dotfile: https://www.doxygen.nl/manual/commands.html#cmddotfile

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``.

.. code-block:: python

    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 <https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html#confval-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:

- :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:

    .. csv-table::
        :header: graph relevance, configuration option

        files included within, `INCLUDE_GRAPH <https://www.doxygen.nl/manual/config.html#cfg_include_graph>`_
        files included by, `INCLUDED_BY_GRAPH <https://www.doxygen.nl/manual/config.html#cfg_included_by_graph>`_
        inheritance, `CLASS_GRAPH <https://www.doxygen.nl/manual/config.html#cfg_class_graph>`_
        collaboration, `COLLABORATION_GRAPH <https://www.doxygen.nl/manual/config.html#cfg_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 <doxygen.html#diagrams>`_

Example Graphs
--------------

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

.. code-block:: rst

    .. doxygenpage:: dotgraphs
        :project: dot_graphs

This will render as:

.. doxygenpage:: dotgraphs
    :project: dot_graphs