1 .. include:: ../disclaimer-zh_CN.rst 1 .. include:: ../disclaimer-zh_CN.rst
2 2
3 :Original: Documentation/doc-guide/sphinx.rst 3 :Original: Documentation/doc-guide/sphinx.rst
4 4
5 :译者: 吴想成 Wu XiangCheng <bobwxc@email. 5 :译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
6 6
7 .. _sphinxdoc_zh: 7 .. _sphinxdoc_zh:
8 8
9 简介 9 简介
10 ==== 10 ====
11 11
12 Linux内核使用 `Sphinx <http://www.sphinx-d 12 Linux内核使用 `Sphinx <http://www.sphinx-doc.org/>`_ 来把 ``Documentation``
13 下的 `reStructuredText <http://docutils.sour 13 下的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 文件转
14 换成漂亮的文档。使用 ``make htmldocs 14 换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML
15 或PDF格式的文档。生成的文档放在 15 或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。
16 16
17 reStructuredText文件可能包含包含来自 17 reStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。
18 通常它们用于描述代码的功能、类 18 通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和
19 格式，但除此之外，它们还被作为r 19 格式，但除此之外，它们还被作为reStructuredText处理。
20 20
21 最后，有成千上万的纯文本文档文 21 最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移，
22 其中一些可能会转换为reStructuredText 22 其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。
23 23
24 .. _sphinx_install_zh: 24 .. _sphinx_install_zh:
25 25
26 安装Sphinx 26 安装Sphinx
27 ========== 27 ==========
28 28
29 Documentation/ 下的ReST文件现在使用sph !! 29 Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。
30 30
31 这有一个脚本可以检查Sphinx的依赖 31 这有一个脚本可以检查Sphinx的依赖项。更多详细信息见
32 :ref:`sphinx-pre-install_zh` 。 32 :ref:`sphinx-pre-install_zh` 。
33 33
34 大多数发行版都附带了Sphinx，但是 34 大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它
35 或其他一些Python包导致文档构建中 35 或其他一些Python包导致文档构建中断的情况并不少见。
36 36
37 避免此情况的一种方法是使用与发 37 避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用
38 ``virtualenv-3`` 或 ``virtualenv`` 在虚拟 38 ``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境中安装Sphinx，具体取决于发行版
39 如何打包Python3。 39 如何打包Python3。
40 40
41 .. note:: 41 .. note::
42 42
>> 43 #) 低于1.5版本的Sphinx无法与Python的0.13.1或更高版本docutils一起正常工作。
>> 44 如果您想使用这些版本，那么应该运行 ``pip install 'docutils==0.12'`` 。
>> 45
43 #) html输出建议使用RTD主题。根据 46 #) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用
44 ``pip install sphinx_rtd_theme`` 单独 47 ``pip install sphinx_rtd_theme`` 单独安装。
45 48
46 #) 一些ReST页面包含数学表达式。 49 #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX
47 编写的。它需要安装amsfonts和am 50 编写的。它需要安装amsfonts和amsmath宏包，以便显示。
48 51
49 总之，如您要安装Sphinx 2.4.4版本， !! 52 总之，如您要安装Sphinx 1.7.9版本，应执行::
50 53
51 $ virtualenv sphinx_2.4.4 !! 54 $ virtualenv sphinx_1.7.9
52 $ . sphinx_2.4.4/bin/activate !! 55 $ . sphinx_1.7.9/bin/activate
53 (sphinx_2.4.4) $ pip install -r Documen !! 56 (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt
54 57
55 在运行 ``. sphinx_2.4.4/bin/activate`` 之 !! 58 在运行 ``. sphinx_1.7.9/bin/activate`` 之后，提示符将变化，以指示您正在使用新
56 环境。如果您打开了一个新的shell 59 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再
57 次进入虚拟环境中。 60 次进入虚拟环境中。
58 61
59 图片输出 62 图片输出
60 -------- 63 --------
61 64
62 内核文档构建系统包含一个扩展， 65 内核文档构建系统包含一个扩展，可以处理GraphViz和SVG格式的图像（参见
63 :ref:`sphinx_kfigure_zh` ）。 66 :ref:`sphinx_kfigure_zh` ）。
64 67
65 为了让它工作，您需要同时安装Grap 68 为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包，
66 构建系统仍将构建文档，但不会在 69 构建系统仍将构建文档，但不会在输出中包含任何图像。
67 70
68 PDF和LaTeX构建 71 PDF和LaTeX构建
69 -------------- 72 --------------
70 73
71 目前只有Sphinx 2.4及更高版本才支持 !! 74 目前只有Sphinx 1.4及更高版本才支持这种构建。
72 75
73 对于PDF和LaTeX输出，还需要 ``XeLaTeX` 76 对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实
74 存在） 77 存在）
75 78
76 根据发行版的不同，您可能还需要 79 根据发行版的不同，您可能还需要安装一系列 ``texlive`` 软件包，这些软件包提供了
77 ``XeLaTeX`` 工作所需的最小功能集。 80 ``XeLaTeX`` 工作所需的最小功能集。
78 81
79 .. _sphinx-pre-install_zh: 82 .. _sphinx-pre-install_zh:
80 83
81 检查Sphinx依赖项 84 检查Sphinx依赖项
82 ---------------- 85 ----------------
83 86
84 这有一个脚本可以自动检查Sphinx依 87 这有一个脚本可以自动检查Sphinx依赖项。如果它认得您的发行版，还会提示您所用发行
85 版的安装命令:: 88 版的安装命令::
86 89
87 $ ./scripts/sphinx-pre-install 90 $ ./scripts/sphinx-pre-install
88 Checking if the needed tools for Fedor 91 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
89 Warning: better to also install "texli 92 Warning: better to also install "texlive-luatex85".
90 You should run: 93 You should run:
91 94
92 sudo dnf install -y texlive-lu 95 sudo dnf install -y texlive-luatex85
93 /usr/bin/virtualenv sphinx_2.4 !! 96 /usr/bin/virtualenv sphinx_1.7.9
94 . sphinx_2.4.4/bin/activate !! 97 . sphinx_1.7.9/bin/activate
95 pip install -r Documentation/s 98 pip install -r Documentation/sphinx/requirements.txt
96 99
97 Can't build as 1 mandatory dependency 100 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
98 101
99 默认情况下，它会检查html和PDF的所 102 默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的
100 需求，并假设将使用虚拟Python环境 103 需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依
101 赖项则是可选的。 104 赖项则是可选的。
102 105
103 它支持两个可选参数： 106 它支持两个可选参数：
104 107
105 ``--no-pdf`` 108 ``--no-pdf``
106 109
107 禁用PDF检查； 110 禁用PDF检查；
108 111
109 ``--no-virtualenv`` 112 ``--no-virtualenv``
110 113
111 使用Sphinx的系统打包，而不 114 使用Sphinx的系统打包，而不是Python虚拟环境。
112 115
113 Sphinx构建 116 Sphinx构建
114 ========== 117 ==========
115 118
116 生成文档的常用方法是运行 ``make ht 119 生成文档的常用方法是运行 ``make htmldocs`` 或 ``make pdfdocs`` 。还有其它可用
117 的格式：请参阅 ``make help`` 的文档 120 的格式：请参阅 ``make help`` 的文档部分。生成的文档放在 ``Documentation/output``
118 下相应格式的子目录中。 121 下相应格式的子目录中。
119 122
120 要生成文档，显然必须安装Sphinx（ 123 要生成文档，显然必须安装Sphinx（ ``sphinx-build`` ）。要让HTML输出更漂亮，可以
121 使用Read the Docs Sphinx主题（ ``sphinx_r 124 使用Read the Docs Sphinx主题（ ``sphinx_rtd_theme`` ）。对于PDF输出，您还需要
122 ``XeLaTeX`` 和来自ImageMagick（https://www 125 ``XeLaTeX`` 和来自ImageMagick（https://www.imagemagick.org）的 ``convert(1)`` 。
123 所有这些软件在大多发行版中都可 126 所有这些软件在大多发行版中都可用或已打包。
124 127
125 要传递额外的选项给Sphinx，可以使 128 要传递额外的选项给Sphinx，可以使用make变量 ``SPHINXOPTS`` 。例如，使用
126 ``make SPHINXOPTS=-v htmldocs`` 获得更详 129 ``make SPHINXOPTS=-v htmldocs`` 获得更详细的输出。
127 130
128 131
129 要删除生成的文档，请运行 ``make cl 132 要删除生成的文档，请运行 ``make cleandocs`` 。
130 133
131 编写文档 134 编写文档
132 ======== 135 ========
133 136
134 添加新文档很容易，只需： 137 添加新文档很容易，只需：
135 138
136 1. 在 ``Documentation`` 下某处添加一个 139 1. 在 ``Documentation`` 下某处添加一个新的 ``.rst`` 文件。
137 2. 从 ``Documentation/index.rst`` 中的Sphin 140 2. 从 ``Documentation/index.rst`` 中的Sphinx `主目录树`_ 链接到它。
138 141
139 .. _主目录树: http://www.sphinx-doc.org/en 142 .. _主目录树: http://www.sphinx-doc.org/en/stable/markup/toctree.html
140 143
141 对于简单的文档（比如您现在正在 144 对于简单的文档（比如您现在正在阅读的文档），这通常已经足够好了，但是对于较大
142 的文档，最好创建一个子目录（或 145 的文档，最好创建一个子目录（或者使用现有的子目录）。例如，图形子系统文档位于
143 ``Documentation/gpu`` 下，拆分为多个 `` 146 ``Documentation/gpu`` 下，拆分为多个 ``.rst`` 文件，并具有从主目录链接来的单
144 独索引 ``index.rst`` （有自己的目录 147 独索引 ``index.rst`` （有自己的目录树 ``toctree`` ）。
145 148
146 请参阅 `Sphinx <http://www.sphinx-doc.org/> 149 请参阅 `Sphinx <http://www.sphinx-doc.org/>`_ 和 `reStructuredText
147 <http://docutils.sourceforge.net/rst.html>`_ 150 <http://docutils.sourceforge.net/rst.html>`_ 的文档，以了解如何使用它们。
148 特别是Sphinx `reStructuredText 基础`_ 这 151 特别是Sphinx `reStructuredText 基础`_ 这是开始学习使用reStructuredText的
149 好地方。还有一些 `Sphinx 特殊标记 152 好地方。还有一些 `Sphinx 特殊标记结构`_ 。
150 153
151 .. _reStructuredText 基础: http://www.sphinx 154 .. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.html
152 .. _Sphinx 特殊标记结构: http://www.sphi 155 .. _Sphinx 特殊标记结构: http://www.sphinx-doc.org/en/stable/markup/index.html
153 156
154 内核文档的具体指南 157 内核文档的具体指南
155 ------------------ 158 ------------------
156 159
157 这是一些内核文档的具体指南： 160 这是一些内核文档的具体指南：
158 161
159 * 请不要过于痴迷转换格式到reStruct 162 * 请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档
160 应该是纯文本，格式应足够一致 163 应该是纯文本，格式应足够一致，以便可以转换为其他格式。
161 164
162 * 将现有文档转换为reStructuredText时 165 * 将现有文档转换为reStructuredText时，请尽量减少格式更改。
163 166
164 * 在转换文档时，还要更新内容， 167 * 在转换文档时，还要更新内容，而不仅仅是格式。
165 168
166 * 请遵循标题修饰符的顺序： 169 * 请遵循标题修饰符的顺序：
167 170
168 1. ``=`` 文档标题，要有上线:: 171 1. ``=`` 文档标题，要有上线::
169 172
170 ======== 173 ========
171 文档标题 174 文档标题
172 ======== 175 ========
173 176
174 2. ``=`` 章:: 177 2. ``=`` 章::
175 178
176 章标题 179 章标题
177 ====== 180 ======
178 181
179 3. ``-`` 节:: 182 3. ``-`` 节::
180 183
181 节标题 184 节标题
182 ------ 185 ------
183 186
184 4. ``~`` 小节:: 187 4. ``~`` 小节::
185 188
186 小节标题 189 小节标题
187 ~~~~~~~~ 190 ~~~~~~~~
188 191
189 尽管RST没有规定具体的顺序（“ 192 尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终
190 按照的顺序将是实际遇到的顺序 193 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。
191 194
192 * 对于插入固定宽度的文本块（用 195 * 对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不
193 大的内容，尤其是短代码段； ``.. 196 大的内容，尤其是短代码段； ``.. code-block:: <language>`` 用于需要语法高亮的
194 较长代码块。对于嵌入到文本中 197 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。
195 198
196 199
197 C域 200 C域
198 --- 201 ---
199 202
200 **Sphinx C域（Domain）** （name c）适用 203 **Sphinx C域（Domain）** （name c）适用于C API文档。例如，函数原型：
201 204
202 .. code-block:: rst 205 .. code-block:: rst
203 206
204 .. c:function:: int ioctl( int fd, int req 207 .. c:function:: int ioctl( int fd, int request )
205 208
206 内核文档的C域有一些附加特性。例 209 内核文档的C域有一些附加特性。例如，您可以使用诸如 ``open`` 或 ``ioctl`` 这样的
207 通用名称重命名函数的引用名称： 210 通用名称重命名函数的引用名称：
208 211
209 .. code-block:: rst 212 .. code-block:: rst
210 213
211 .. c:function:: int ioctl( int fd, int re 214 .. c:function:: int ioctl( int fd, int request )
212 :name: VIDIOC_LOG_STATUS 215 :name: VIDIOC_LOG_STATUS
213 216
214 函数名称（例如ioctl）仍保留在输 217 函数名称（例如ioctl）仍保留在输出中，但引用名称从 ``ioctl`` 变为
215 ``VIDIOC_LOG_STATUS`` 。此函数的索引项 218 ``VIDIOC_LOG_STATUS`` 。此函数的索引项也变为 ``VIDIOC_LOG_STATUS`` 。
216 219
217 请注意，不需要使用 ``c:func:`` 生成 220 请注意，不需要使用 ``c:func:`` 生成函数文档的交叉引用。由于一些Sphinx扩展的
218 神奇力量，如果给定函数名的索引 221 神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 ``function()``
219 的引用转换为交叉引用。如果在内 222 的引用转换为交叉引用。如果在内核文档中看到 ``c:func:`` 的用法，请删除它。
220 223
221 224
222 列表 225 列表
223 ---- 226 ----
224 227
225 我们建议使用 *列式表* 格式。 *列 228 我们建议使用 *列式表* 格式。 *列式表* 格式是二级列表。与ASCII艺术相比，它们对
226 文本文件的读者来说可能没有那么 229 文本文件的读者来说可能没有那么舒适。但其优点是易于创建或修改，而且修改的差异
227 （diff）更有意义，因为差异仅限于 230 （diff）更有意义，因为差异仅限于修改的内容。
228 231
229 *平铺表* 也是一个二级列表，类似 232 *平铺表* 也是一个二级列表，类似于 *列式表* ，但具有一些额外特性：
230 233
231 * 列范围：使用 ``cspan`` 修饰，可以 234 * 列范围：使用 ``cspan`` 修饰，可以通过其他列扩展单元格
232 235
233 * 行范围：使用 ``rspan`` 修饰，可以 236 * 行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格
234 237
235 * 自动将表格行最右边的单元格扩 238 * 自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用
236 ``:fill-cells:`` 选项，此行为可以从 239 ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动
237 插入（空）单元格，而不是扩展 240 插入（空）单元格，而不是扩展合并到最后一个单元格。
238 241
239 选项： 242 选项：
240 243
241 * ``:header-rows:`` [int] 标题行计数 244 * ``:header-rows:`` [int] 标题行计数
242 * ``:stub-columns:`` [int] 标题列计数 245 * ``:stub-columns:`` [int] 标题列计数
243 * ``:widths:`` [[int] [int] ... ] 列 246 * ``:widths:`` [[int] [int] ... ] 列宽
244 * ``:fill-cells:`` 插入缺少的单元格 247 * ``:fill-cells:`` 插入缺少的单元格，而不是自动合并缺少的单元格
245 248
246 修饰： 249 修饰：
247 250
248 * ``:cspan:`` [int] 扩展列 251 * ``:cspan:`` [int] 扩展列
249 * ``:rspan:`` [int] 扩展行 252 * ``:rspan:`` [int] 扩展行
250 253
251 下面的例子演示了如何使用这些标 254 下面的例子演示了如何使用这些标记。分级列表的第一级是 *表格行* 。 *表格行* 中
252 只允许一个标记，即该 *表格行* 中 255 只允许一个标记，即该 *表格行* 中的单元格列表。 *comments* （ ``..`` ）和
253 *targets* 例外（例如引用 ``:ref:`最后 256 *targets* 例外（例如引用 ``:ref:`最后一行 <last row_zh>``` / :ref:`最后一行
254 <last row_zh>` ）。 257 <last row_zh>` ）。
255 258
256 .. code-block:: rst 259 .. code-block:: rst
257 260
258 .. flat-table:: 表格标题 261 .. flat-table:: 表格标题
259 :widths: 2 1 1 3 262 :widths: 2 1 1 3
260 263
261 * - 表头 列1 264 * - 表头 列1
262 - 表头 列2 265 - 表头 列2
263 - 表头 列3 266 - 表头 列3
264 - 表头 列4 267 - 表头 列4
265 268
266 * - 行1 269 * - 行1
267 - 字段1.1 270 - 字段1.1
268 - 字段1.2（自动扩展） 271 - 字段1.2（自动扩展）
269 272
270 * - 行2 273 * - 行2
271 - 字段2.1 274 - 字段2.1
272 - :rspan:`1` :cspan:`1` 字段2.2~3.3 275 - :rspan:`1` :cspan:`1` 字段2.2~3.3
273 276
274 * .. _`last row_zh`: 277 * .. _`last row_zh`:
275 278
276 - 行3 279 - 行3
277 280
278 渲染效果： 281 渲染效果：
279 282
280 .. flat-table:: 表格标题 283 .. flat-table:: 表格标题
281 :widths: 2 1 1 3 284 :widths: 2 1 1 3
282 285
283 * - 表头 列1 286 * - 表头 列1
284 - 表头 列2 287 - 表头 列2
285 - 表头 列3 288 - 表头 列3
286 - 表头 列4 289 - 表头 列4
287 290
288 * - 行1 291 * - 行1
289 - 字段1.1 292 - 字段1.1
290 - 字段1.2（自动扩展） 293 - 字段1.2（自动扩展）
291 294
292 * - 行2 295 * - 行2
293 - 字段2.1 296 - 字段2.1
294 - :rspan:`1` :cspan:`1` 字段2.2~3.3 297 - :rspan:`1` :cspan:`1` 字段2.2~3.3
295 298
296 * .. _`last row_zh`: 299 * .. _`last row_zh`:
297 300
298 - 行3 301 - 行3
299 302
300 交叉引用 303 交叉引用
301 -------- 304 --------
302 305
303 从一页文档到另一页文档的交叉引 306 从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式
304 要求。路径可以是绝对路径或相对 307 要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要
305 交叉引用此页，以下写法皆可，取 308 交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 ``.rst`` 扩展名是可选
306 的）:: 309 的）::
307 310
308 参见 Documentation/doc-guide/sphinx.rst 311 参见 Documentation/doc-guide/sphinx.rst 。此法始终可用。
309 请查看 sphinx.rst ，仅在同级目录 312 请查看 sphinx.rst ，仅在同级目录中有效。
310 请阅读 ../sphinx.rst ，上级目录中 313 请阅读 ../sphinx.rst ，上级目录中的文件。
311 314
312 如果要使用相对路径，则需要使用S 315 如果要使用相对路径，则需要使用Sphinx的 ``doc`` 修饰。例如，从同一目录引用此页
313 的操作如下:: 316 的操作如下::
314 317
315 参见 :doc:`sphinx文档的自定义链 318 参见 :doc:`sphinx文档的自定义链接文本 <sphinx>`.
316 319
317 对于大多数用例，前者是首选，因 320 对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一
318 个没有任何特殊作用的 ``:doc:`` 用 321 个没有任何特殊作用的 ``:doc:`` 用法，请将其转换为文档路径。
319 322
320 有关交叉引用kernel-doc函数或类型的 323 有关交叉引用kernel-doc函数或类型的信息，请参阅
321 Documentation/doc-guide/kernel-doc.rst 。 324 Documentation/doc-guide/kernel-doc.rst 。
322 325
323 .. _sphinx_kfigure_zh: 326 .. _sphinx_kfigure_zh:
324 327
325 图形图片 328 图形图片
326 ======== 329 ========
327 330
328 如果要添加图片，应该使用 ``kernel- 331 如果要添加图片，应该使用 ``kernel-figure`` 和 ``kernel-image`` 指令。例如，
329 要插入具有可缩放图像格式的图形 332 要插入具有可缩放图像格式的图形，请使用SVG（:ref:`svg_image_example_zh` ）::
330 333
331 .. kernel-figure:: ../../../doc-guide/svg 334 .. kernel-figure:: ../../../doc-guide/svg_image.svg
332 :alt: 简易 SVG 图片 335 :alt: 简易 SVG 图片
333 336
334 SVG 图片示例 337 SVG 图片示例
335 338
336 .. _svg_image_example_zh: 339 .. _svg_image_example_zh:
337 340
338 .. kernel-figure:: ../../../doc-guide/svg_ima 341 .. kernel-figure:: ../../../doc-guide/svg_image.svg
339 :alt: 简易 SVG 图片 342 :alt: 简易 SVG 图片
340 343
341 SVG 图片示例 344 SVG 图片示例
342 345
343 内核figure（和image）指令支持 DOT 格 346 内核figure（和image）指令支持 DOT 格式文件，请参阅
344 347
345 * DOT：http://graphviz.org/pdf/dotguide.pdf 348 * DOT：http://graphviz.org/pdf/dotguide.pdf
346 * Graphviz：http://www.graphviz.org/content/d 349 * Graphviz：http://www.graphviz.org/content/dot-language
347 350
348 一个简单的例子（:ref:`hello_dot_file_z 351 一个简单的例子（:ref:`hello_dot_file_zh` ）::
349 352
350 .. kernel-figure:: ../../../doc-guide/hello 353 .. kernel-figure:: ../../../doc-guide/hello.dot
351 :alt: 你好，世界 354 :alt: 你好，世界
352 355
353 DOT 示例 356 DOT 示例
354 357
355 .. _hello_dot_file_zh: 358 .. _hello_dot_file_zh:
356 359
357 .. kernel-figure:: ../../../doc-guide/hello.d 360 .. kernel-figure:: ../../../doc-guide/hello.dot
358 :alt: 你好，世界 361 :alt: 你好，世界
359 362
360 DOT 示例 363 DOT 示例
361 364
362 嵌入的渲染标记（或语言），如Grap 365 嵌入的渲染标记（或语言），如Graphviz的 **DOT** 由 ``kernel-render`` 指令提供::
363 366
364 .. kernel-render:: DOT 367 .. kernel-render:: DOT
365 :alt: 有向图 368 :alt: 有向图
366 :caption: 嵌入式 **DOT** (Graphviz) 369 :caption: 嵌入式 **DOT** (Graphviz) 代码
367 370
368 digraph foo { 371 digraph foo {
369 "五棵松" -> "国贸"; 372 "五棵松" -> "国贸";
370 } 373 }
371 374
372 如何渲染取决于安装的工具。如果 375 如何渲染取决于安装的工具。如果安装了Graphviz，您将看到一个矢量图像。否则，原始
373 标记将作为 *文字块* 插入（:ref:`hel 376 标记将作为 *文字块* 插入（:ref:`hello_dot_render_zh` ）。
374 377
375 .. _hello_dot_render_zh: 378 .. _hello_dot_render_zh:
376 379
377 .. kernel-render:: DOT 380 .. kernel-render:: DOT
378 :alt: 有向图 381 :alt: 有向图
379 :caption: 嵌入式 **DOT** (Graphviz) 代 382 :caption: 嵌入式 **DOT** (Graphviz) 代码
380 383
381 digraph foo { 384 digraph foo {
382 "五棵松" -> "国贸"; 385 "五棵松" -> "国贸";
383 } 386 }
384 387
385 *render* 指令包含 *figure* 指令中已知 388 *render* 指令包含 *figure* 指令中已知的所有选项，以及选项 ``caption`` 。如果
386 ``caption`` 有值，则插入一个 *figure* 389 ``caption`` 有值，则插入一个 *figure* 节点，若无，则插入一个 *image* 节点。
387 如果您想引用它，还需要一个 ``capt 390 如果您想引用它，还需要一个 ``caption`` （:ref:`hello_svg_render_zh` ）。
388 391
389 嵌入式 **SVG**:: 392 嵌入式 **SVG**::
390 393
391 .. kernel-render:: SVG 394 .. kernel-render:: SVG
392 :caption: 嵌入式 **SVG** 标记 395 :caption: 嵌入式 **SVG** 标记
393 :alt: 右上箭头 396 :alt: 右上箭头
394 397
395 <?xml version="1.0" encoding="UTF-8"?> 398 <?xml version="1.0" encoding="UTF-8"?>
396 <svg xmlns="http://www.w3.org/2000/svg" v 399 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
397 ... 400 ...
398 </svg> 401 </svg>
399 402
400 .. _hello_svg_render_zh: 403 .. _hello_svg_render_zh:
401 404
402 .. kernel-render:: SVG 405 .. kernel-render:: SVG
403 :caption: 嵌入式 **SVG** 标记 406 :caption: 嵌入式 **SVG** 标记
404 :alt: 右上箭头 407 :alt: 右上箭头
405 408
406 <?xml version="1.0" encoding="UTF-8"?> 409 <?xml version="1.0" encoding="UTF-8"?>
407 <svg xmlns="http://www.w3.org/2000/svg" 410 <svg xmlns="http://www.w3.org/2000/svg"
408 version="1.1" baseProfile="full" width="7 411 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
409 <line x1="180" y1="370" x2="500" y2="50" st 412 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
410 <polygon points="585 0 525 25 585 50" trans 413 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
411 </svg> 414 </svg>
412 415
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.