- Home
- Get it
- Docs
- Extend/Develop

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

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

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

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

New in version 1.0: All three directives support an `alt` option that determines the image’s alternate text for HTML output. If not given, the alternate text defaults to the graphviz code.

New in version 1.1: All three directives support a `caption` option that can be used to give a caption to the diagram.

Changed in version 1.4: All three directives support a `graphviz_dot` option that can be switch the `dot` command within the directive.

New in version 1.5: All three directives support a `align` option to align the graph horizontal. The values “left”, “center”, “right” are allowed.

New in version 1.6: All three directives support a `name` option to set the label to graph.

There are also these new config values:

`graphviz_dot`

  The command name with which to invoke `dot`. The default is `'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 -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html

`graphviz_dot_args`

  Additional command-line arguments to give to dot, as a list. The default is an empty 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`

  The output format for Graphviz when building HTML files. This must be either `'png'` or `'svg'`; the default is `'png'`. 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="http://sphinx-doc.org", target="_top"];
               b [label="other"];
               a -> b;
           }

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