summaryrefslogtreecommitdiffstats
path: root/doc/usage/extensions/graphviz.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/usage/extensions/graphviz.rst
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage/extensions/graphviz.rst')
-rw-r--r--doc/usage/extensions/graphviz.rst239
1 files changed, 239 insertions, 0 deletions
diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst
new file mode 100644
index 0000000..c134f6d
--- /dev/null
+++ b/doc/usage/extensions/graphviz.rst
@@ -0,0 +1,239 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs
+=================================================
+
+.. module:: sphinx.ext.graphviz
+ :synopsis: Support for Graphviz graphs.
+
+.. versionadded:: 0.6
+
+This extension allows you to embed `Graphviz <https://graphviz.org/>`_ graphs in
+your documents.
+
+It adds these directives:
+
+.. rst:directive:: 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
+ :confval:`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 :rst:dir:`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.
+
+ .. versionchanged:: 1.1
+ Added support for external files.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: alt: alternate text
+ :type: text
+
+ The alternate text of the graph. By default, the graph code is used to
+ the alternate text.
+
+ .. versionadded:: 1.0
+
+ .. rst:directive:option:: align: alignment of the graph
+ :type: left, center or right
+
+ The horizontal alignment of the graph.
+
+ .. versionadded:: 1.5
+
+ .. rst:directive:option:: caption: caption of the graph
+ :type: text
+
+ The caption of the graph.
+
+ .. versionadded:: 1.1
+
+ .. rst:directive:option:: layout: layout type of the graph
+ :type: text
+
+ The layout of the graph (ex. ``dot``, ``neato`` and so on). A path to the
+ graphviz commands are also allowed. By default, :confval:`graphviz_dot`
+ is used.
+
+ .. versionadded:: 1.4
+ .. versionchanged:: 2.2
+
+ Renamed from ``graphviz_dot``
+
+ .. rst:directive:option:: name: label
+ :type: text
+
+ The label of the graph.
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: class: class names
+ :type: a list of class names separated by spaces
+
+ The class name of the graph.
+
+ .. versionadded:: 2.4
+
+
+.. rst:directive:: 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.
+
+ .. rubric:: options
+
+ Same as :rst:dir:`graphviz`.
+
+ .. rst:directive:option:: alt: alternate text
+ :type: text
+
+ .. versionadded:: 1.0
+
+ .. rst:directive:option:: align: alignment of the graph
+ :type: left, center or right
+
+ .. versionadded:: 1.5
+
+ .. rst:directive:option:: caption: caption of the graph
+ :type: text
+
+ .. versionadded:: 1.1
+
+ .. rst:directive:option:: layout: layout type of the graph
+ :type: text
+
+ .. versionadded:: 1.4
+ .. versionchanged:: 2.2
+
+ Renamed from ``graphviz_dot``
+
+ .. rst:directive:option:: name: label
+ :type: text
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: class: class names
+ :type: a list of class names separated by spaces
+
+ The class name of the graph.
+
+ .. versionadded:: 2.4
+
+
+.. rst:directive:: 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";
+
+ .. rubric:: options
+
+ Same as :rst:dir:`graphviz`.
+
+ .. rst:directive:option:: alt: alternate text
+ :type: text
+
+ .. versionadded:: 1.0
+
+ .. rst:directive:option:: align: alignment of the graph
+ :type: left, center or right
+
+ .. versionadded:: 1.5
+
+ .. rst:directive:option:: caption: caption of the graph
+ :type: text
+
+ .. versionadded:: 1.1
+
+ .. rst:directive:option:: layout: layout type of the graph
+ :type: text
+
+ .. versionadded:: 1.4
+ .. versionchanged:: 2.2
+
+ Renamed from ``graphviz_dot``
+
+ .. rst:directive:option:: name: label
+ :type: text
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: class: class names
+ :type: a list of class names separated by spaces
+
+ The class name of the graph.
+
+ .. versionadded:: 2.4
+
+
+There are also these config values:
+
+.. confval:: 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
+ :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
+ option should be preferable, like this::
+
+ sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
+
+.. confval:: 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.
+
+.. confval:: 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;
+ }
+
+ .. versionadded:: 1.0
+ Previously, output always was PNG.