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