1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
.. highlight:: rst
: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 (e.g. ``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 -M html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build
.. 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.
|
