Documentation/translations/zh_CN/doc-guide/sphinx.rst

   1 .. include:: ../disclaimer-zh_CN.rst
   2
   3 :Original: Documentation/doc-guide/sphinx.rst
   4
   5 :译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
   6
   7 .. _sphinxdoc_zh:
   8
   9 简介
  10 ====
  11
  12 Linux内核使用 `Sphinx <http://www.sphinx-doc.org/>`_ 来把 ``Documentation``
  13 下的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 文件转
  14 换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML
  15 或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。
  16
  17 reStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。
  18 通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和
  19 格式，但除此之外，它们还被作为reStructuredText处理。
  20
  21 最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移，
  22 其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。
  23
  24 .. _sphinx_install_zh:
  25
  26 安装Sphinx
  27 ==========
  28
  29 Documentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。
  30
  31 这有一个脚本可以检查Sphinx的依赖项。更多详细信息见
  32 :ref:`sphinx-pre-install_zh` 。
  33
  34 大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它
  35 或其他一些Python包导致文档构建中断的情况并不少见。
  36
  37 避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用
  38 ``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境中安装Sphinx，具体取决于发行版
  39 如何打包Python3。
  40
  41 .. note::
  42
  43    #) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用
  44       ``pip install sphinx_rtd_theme`` 单独安装。
  45
  46    #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX
  47       编写的。它需要安装amsfonts和amsmath宏包，以便显示。
  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 Documentation/sphinx/requirements.txt
  54
  55 在运行 ``. sphinx_2.4.4/bin/activate`` 之后，提示符将变化，以指示您正在使用新
  56 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再
  57 次进入虚拟环境中。
  58
  59 图片输出
  60 --------
  61
  62 内核文档构建系统包含一个扩展，可以处理GraphViz和SVG格式的图像（参见
  63 :ref:`sphinx_kfigure_zh` ）。
  64
  65 为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包，
  66 构建系统仍将构建文档，但不会在输出中包含任何图像。
  67
  68 PDF和LaTeX构建
  69 --------------
  70
  71 目前只有Sphinx 2.4及更高版本才支持这种构建。
  72
  73 对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实
  74 存在）
  75
  76 根据发行版的不同，您可能还需要安装一系列 ``texlive`` 软件包，这些软件包提供了
  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 Fedora release 26 (Twenty Six) are available
  89         Warning: better to also install "texlive-luatex85".
  90         You should run:
  91
  92                 sudo dnf install -y texlive-luatex85
  93                 /usr/bin/virtualenv sphinx_2.4.4
  94                 . sphinx_2.4.4/bin/activate
  95                 pip install -r Documentation/sphinx/requirements.txt
  96
  97         Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
  98
  99 默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的
 100 需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依
 101 赖项则是可选的。
 102
 103 它支持两个可选参数：
 104
 105 ``--no-pdf``
 106
 107         禁用PDF检查；
 108
 109 ``--no-virtualenv``
 110
 111         使用Sphinx的系统打包，而不是Python虚拟环境。
 112
 113 Sphinx构建
 114 ==========
 115
 116 生成文档的常用方法是运行 ``make htmldocs`` 或 ``make pdfdocs`` 。还有其它可用
 117 的格式：请参阅 ``make help`` 的文档部分。生成的文档放在 ``Documentation/output``
 118 下相应格式的子目录中。
 119
 120 要生成文档，显然必须安装Sphinx（ ``sphinx-build`` ）。要让HTML输出更漂亮，可以
 121 使用Read the Docs Sphinx主题（ ``sphinx_rtd_theme`` ）。对于PDF输出，您还需要
 122 ``XeLaTeX`` 和来自ImageMagick（https://www.imagemagick.org）的 ``convert(1)`` 。
 123 所有这些软件在大多发行版中都可用或已打包。
 124
 125 要传递额外的选项给Sphinx，可以使用make变量 ``SPHINXOPTS`` 。例如，使用
 126 ``make SPHINXOPTS=-v htmldocs`` 获得更详细的输出。
 127
 128
 129 要删除生成的文档，请运行 ``make cleandocs`` 。
 130
 131 编写文档
 132 ========
 133
 134 添加新文档很容易，只需：
 135
 136 1. 在 ``Documentation`` 下某处添加一个新的 ``.rst`` 文件。
 137 2. 从 ``Documentation/index.rst`` 中的Sphinx `主目录树`_ 链接到它。
 138
 139 .. _主目录树: http://www.sphinx-doc.org/en/stable/markup/toctree.html
 140
 141 对于简单的文档（比如您现在正在阅读的文档），这通常已经足够好了，但是对于较大
 142 的文档，最好创建一个子目录（或者使用现有的子目录）。例如，图形子系统文档位于
 143 ``Documentation/gpu`` 下，拆分为多个 ``.rst`` 文件，并具有从主目录链接来的单
 144 独索引 ``index.rst`` （有自己的目录树 ``toctree`` ）。
 145
 146 请参阅 `Sphinx <http://www.sphinx-doc.org/>`_ 和 `reStructuredText
 147 <http://docutils.sourceforge.net/rst.html>`_ 的文档，以了解如何使用它们。
 148 特别是Sphinx `reStructuredText 基础`_ 这是开始学习使用reStructuredText的
 149 好地方。还有一些 `Sphinx 特殊标记结构`_ 。
 150
 151 .. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.html
 152 .. _Sphinx 特殊标记结构: http://www.sphinx-doc.org/en/stable/markup/index.html
 153
 154 内核文档的具体指南
 155 ------------------
 156
 157 这是一些内核文档的具体指南：
 158
 159 * 请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档
 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   大的内容，尤其是短代码段； ``.. code-block:: <language>`` 用于需要语法高亮的
 194   较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。
 195
 196
 197 C域
 198 ---
 199
 200 **Sphinx C域（Domain）** （name c）适用于C API文档。例如，函数原型：
 201
 202 .. code-block:: rst
 203
 204     .. c:function:: int ioctl( int fd, int request )
 205
 206 内核文档的C域有一些附加特性。例如，您可以使用诸如 ``open`` 或 ``ioctl`` 这样的
 207 通用名称重命名函数的引用名称：
 208
 209 .. code-block:: rst
 210
 211      .. c:function:: int ioctl( int fd, int request )
 212         :name: VIDIOC_LOG_STATUS
 213
 214 函数名称（例如ioctl）仍保留在输出中，但引用名称从 ``ioctl`` 变为
 215 ``VIDIOC_LOG_STATUS`` 。此函数的索引项也变为 ``VIDIOC_LOG_STATUS`` 。
 216
 217 请注意，不需要使用 ``c:func:`` 生成函数文档的交叉引用。由于一些Sphinx扩展的
 218 神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 ``function()``
 219 的引用转换为交叉引用。如果在内核文档中看到 ``c:func:`` 的用法，请删除它。
 220
 221
 222 列表
 223 ----
 224
 225 我们建议使用 *列式表* 格式。 *列式表* 格式是二级列表。与ASCII艺术相比，它们对
 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 只允许一个标记，即该 *表格行* 中的单元格列表。 *comments* （ ``..`` ）和
 253 *targets* 例外（例如引用 ``:ref:`最后一行 <last row_zh>``` / :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 要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要
 305 交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 ``.rst`` 扩展名是可选
 306 的）::
 307
 308     参见 Documentation/doc-guide/sphinx.rst 。此法始终可用。
 309     请查看 sphinx.rst ，仅在同级目录中有效。
 310     请阅读 ../sphinx.rst ，上级目录中的文件。
 311
 312 如果要使用相对路径，则需要使用Sphinx的 ``doc`` 修饰。例如，从同一目录引用此页
 313 的操作如下::
 314
 315     参见 :doc:`sphinx文档的自定义链接文本 <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-figure`` 和 ``kernel-image`` 指令。例如，
 329 要插入具有可缩放图像格式的图形，请使用SVG（:ref:`svg_image_example_zh` ）::
 330
 331     .. kernel-figure::  ../../../doc-guide/svg_image.svg
 332        :alt:    简易 SVG 图片
 333
 334        SVG 图片示例
 335
 336 .. _svg_image_example_zh:
 337
 338 .. kernel-figure::  ../../../doc-guide/svg_image.svg
 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/dot-language
 347
 348 一个简单的例子（:ref:`hello_dot_file_zh` ）::
 349
 350   .. kernel-figure::  ../../../doc-guide/hello.dot
 351      :alt:    你好，世界
 352
 353      DOT 示例
 354
 355 .. _hello_dot_file_zh:
 356
 357 .. kernel-figure::  ../../../doc-guide/hello.dot
 358    :alt:    你好，世界
 359
 360    DOT 示例
 361
 362 嵌入的渲染标记（或语言），如Graphviz的 **DOT** 由 ``kernel-render`` 指令提供::
 363
 364   .. kernel-render:: DOT
 365      :alt: 有向图
 366      :caption: 嵌入式 **DOT** (Graphviz) 代码
 367
 368      digraph foo {
 369       "五棵松" -> "国贸";
 370      }
 371
 372 如何渲染取决于安装的工具。如果安装了Graphviz，您将看到一个矢量图像。否则，原始
 373 标记将作为 *文字块* 插入（:ref:`hello_dot_render_zh` ）。
 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* 指令中已知的所有选项，以及选项 ``caption`` 。如果
 386 ``caption`` 有值，则插入一个 *figure* 节点，若无，则插入一个 *image* 节点。
 387 如果您想引用它，还需要一个 ``caption`` （:ref:`hello_svg_render_zh` ）。
 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" version="1.1" ...>
 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="70px" height="40px" viewBox="0 0 700 400">
 409    <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
 410    <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
 411    </svg>
 412