mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
133 lines
4.1 KiB
ReStructuredText
133 lines
4.1 KiB
ReStructuredText
.. 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 <http://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.
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
.. 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";
|
|
|
|
|
|
.. versionadded:: 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.
|
|
|
|
.. versionadded:: 1.1
|
|
All three directives support a ``caption`` option that can be used to give a
|
|
caption to the diagram.
|
|
|
|
.. versionchanged:: 1.4
|
|
All three directives support a ``graphviz_dot`` option that can be switch the
|
|
``dot`` command within the directive.
|
|
|
|
.. versionadded:: 1.5
|
|
All three directives support a ``align`` option to align the graph horizontal.
|
|
The values "left", "center", "right" are allowed.
|
|
|
|
.. versionadded:: 1.6
|
|
All three directives support a ``name`` option to set the label to graph.
|
|
|
|
There are also these new 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="http://sphinx-doc.org", target="_top"];
|
|
b [label="other"];
|
|
a -> b;
|
|
}
|
|
|
|
.. versionadded:: 1.0
|
|
Previously, output always was PNG.
|