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

   -[ options ]-

   :alt: alternate text (text)

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

      New in version 1.0.

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

      The horizontal alignment of the graph.

      New in version 1.5.

   :caption: caption of the graph (text)

      The caption of the graph.

      New in version 1.1.

   :layout: layout type of the graph (text)

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

      New in version 1.4.

      Changed in version 2.2: Renamed from "graphviz_dot"

   :name: label (text)

      The label of the graph.

      New in version 1.6.

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

      The class name of the graph.

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

      New in version 1.0.

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

      New in version 1.5.

   :caption: caption of the graph (text)

      New in version 1.1.

   :layout: layout type of the graph (text)

      New in version 1.4.

      Changed in version 2.2: Renamed from "graphviz_dot"

   :name: label (text)

      New in version 1.6.

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

      The class name of the graph.

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

      New in version 1.0.

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

      New in version 1.5.

   :caption: caption of the graph (text)

      New in version 1.1.

   :layout: layout type of the graph (text)

      New in version 1.4.

      Changed in version 2.2: Renamed from "graphviz_dot"

   :name: label (text)

      New in version 1.6.

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

      The class name of the graph.

      New in version 2.4.

There are also these 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="https://www.sphinx-doc.org/", target="_top"];
               b [label="other"];
               a -> b;
           }

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