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