Sphinx

# `sphinx.ext.graphviz` – Add Graphviz graphs

Added in version 0.6.

This extension allows you to embed Graphviz graphs in your documents.

It adds these directives:

.. graphviz::

  Directive to embed graphviz code. The input code for `dot` is given as the content. For example:

      .. graphviz::

         digraph foo {
            "bar" -> "baz";
         }

  In HTML output, the code will be rendered to a PNG or SVG image (see `graphviz_output_format`). In LaTeX output, the code will be rendered to an embeddable PDF file.

  You can also embed external dot files, by giving the file name as an argument to `graphviz` and no additional content:

      .. graphviz:: external.dot

  As for all file references in Sphinx, if the filename is absolute, it is taken as relative to the source directory.

  Changed in version 1.1: Added support for external files.

  options

  :alt: alternate text (text)

    The alternate text of the graph. By default, the graph code is used to the alternate text.

    Added in version 1.0.

  :align: alignment of the graph (left, center or right)

    The horizontal alignment of the graph.

    Added in version 1.5.

  :caption: caption of the graph (text)

    The caption of the graph.

    Added in version 1.1.

  :layout: layout type of the graph (text)

    The layout of the graph (e.g. `dot`, `neato` and so on). A path to the graphviz commands are also allowed. By default, `graphviz_dot` is used.

    Added in version 1.4.

    Changed in version 2.2: Renamed from `graphviz_dot`

  :name: label (text)

    The label of the graph.

    Added in version 1.6.

  :class: class names (a list of class names separated by spaces)

    The class name of the graph.

    Added in version 2.4.

.. graph::

  Directive for embedding a single undirected graph. The name is given as a directive argument, the contents of the graph are the directive content. This is a convenience directive to generate `graph <name> { <content> }`.

  For example:

      .. graph:: foo

         "bar" -- "baz";

  Note

  The graph name is passed unchanged to Graphviz. If it contains non-alphanumeric characters (e.g. a dash), you will have to double-quote it.

  options

  Same as `graphviz`.

  :alt: alternate text (text)

    Added in version 1.0.

  :align: alignment of the graph (left, center or right)

    Added in version 1.5.

  :caption: caption of the graph (text)

    Added in version 1.1.

  :layout: layout type of the graph (text)

    Added in version 1.4.

    Changed in version 2.2: Renamed from `graphviz_dot`

  :name: label (text)

    Added in version 1.6.

  :class: class names (a list of class names separated by spaces)

    The class name of the graph.

    Added in version 2.4.

.. digraph::

  Directive for embedding a single directed graph. The name is given as a directive argument, the contents of the graph are the directive content. This is a convenience directive to generate `digraph <name> { <content> }`.

  For example:

      .. digraph:: foo

         "bar" -> "baz" -> "quux";

  options

  Same as `graphviz`.

  :alt: alternate text (text)

    Added in version 1.0.

  :align: alignment of the graph (left, center or right)

    Added in version 1.5.

  :caption: caption of the graph (text)

    Added in version 1.1.

  :layout: layout type of the graph (text)

    Added in version 1.4.

    Changed in version 2.2: Renamed from `graphviz_dot`

  :name: label (text)

    Added in version 1.6.

  :class: class names (a list of class names separated by spaces)

    The class name of the graph.

    Added in version 2.4.

There are also these config values:

graphviz_dot
  Type:
    `str`
  Default:
    `'dot'`

  The command name with which to invoke `dot`. You may need to set this to a full path if `dot` is not in the executable search path.

  Since this setting is not portable from system to system, it is normally not useful to set it in `conf.py`; rather, giving it on the sphinx-build command line via the `-D` option should be preferable, like this:

      sphinx-build -M html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build

graphviz_dot_args
  Type:
    `Sequence[str]`
  Default:
    `()`

  Additional command-line arguments to give to dot, as a list. This is the right place to set global graph, node or edge attributes via dot’s `-G`, `-N` and `-E` options.

graphviz_output_format
  Type:
    `'png' | 'svg'`
  Default:
    `'png'`

  The output format for Graphviz when building HTML files. This must be either `'png'` or `'svg'`. If `'svg'` is used, in order to make the URL links work properly, an appropriate `target` attribute must be set, such as `"_top"` and `"_blank"`. For example, the link in the following graph should work in the svg output:

      .. graphviz::

           digraph example {
               a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
               b [label="other"];
               a -> b;
           }

  Added in version 1.0: Previously, output always was PNG.