sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextEnglish}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget/doc-guide/sphinxmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/zh_TW/doc-guide/sphinxmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/it_IT/doc-guide/sphinxmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/ja_JP/doc-guide/sphinxmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/ko_KR/doc-guide/sphinxmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/sp_SP/doc-guide/sphinxmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageChinese (Simplified)uh1h hh _documenthsourceNlineNubhnote)}(hX{此文件的目的是为让中文读者更容易阅读和理解，而不是作为一个分支。 因此， 如果您对此文件有任何意见或更新，请先尝试更新原始英文文件。 如果您发现本文档与原始文件有任何不同或者有翻译问题，请发建议或者补丁给 该文件的译者，或者请求中文文档维护者和审阅者的帮助。h]h paragraph)}(hX{此文件的目的是为让中文读者更容易阅读和理解，而不是作为一个分支。 因此， 如果您对此文件有任何意见或更新，请先尝试更新原始英文文件。 如果您发现本文档与原始文件有任何不同或者有翻译问题，请发建议或者补丁给 该文件的译者，或者请求中文文档维护者和审阅者的帮助。h]hX{此文件的目的是为让中文读者更容易阅读和理解，而不是作为一个分支。 因此， 如果您对此文件有任何意见或更新，请先尝试更新原始英文文件。 如果您发现本文档与原始文件有任何不同或者有翻译问题，请发建议或者补丁给 该文件的译者，或者请求中文文档维护者和审阅者的帮助。}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hh5Documentation/translations/zh_CN/disclaimer-zh_CN.rsthKhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh field_list)}(hhh](hfield)}(hhh](h field_name)}(hOriginalh]hOriginal}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhQ/var/lib/git/docbuild/linux/Documentation/translations/zh_CN/doc-guide/sphinx.rsthKubh field_body)}(h#Documentation/doc-guide/sphinx.rst h]h)}(h"Documentation/doc-guide/sphinx.rsth]h"Documentation/doc-guide/sphinx.rst}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h译者h]h译者}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh)}(h*吴想成 Wu XiangCheng h]h)}(h)吴想成 Wu XiangCheng h](h吴想成 Wu XiangCheng <}(hjhhhNhNubh reference)}(hbobwxc@email.cnh]hbobwxc@email.cn}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:bobwxc@email.cnuh1jhjubh>}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]h ]h"]h$]h&]uh1hhhhhhhhKubhtarget)}(h.. _sphinxdoc_zh:h]h}(h]h ]h"]h$]h&]refid sphinxdoc-zhuh1jDhKhhhhhhubhsection)}(hhh](htitle)}(h简介h]h简介}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jWhjThhhhhK ubh)}(hXULinux内核使用 `Sphinx `_ 来把 ``Documentation`` 下的 `reStructuredText `_ 文件转 换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML 或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。h](hLinux内核使用 }(hjghhhNhNubj)}(h&`Sphinx `_h]hSphinx}(hjohhhNhNubah}(h]h ]h"]h$]h&]nameSphinxrefurihttp://www.sphinx-doc.org/uh1jhjgubjE)}(h h]h}(h]sphinxah ]h"]sphinxah$]h&]refurijuh1jD referencedKhjgubh 来把 }(hjghhhNhNubhliteral)}(h``Documentation``h]h Documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjgubh 下的 }(hjghhhNhNubj)}(h>`reStructuredText `_h]hreStructuredText}(hjhhhNhNubah}(h]h ]h"]h$]h&]namereStructuredTextj(http://docutils.sourceforge.net/rst.htmluh1jhjgubjE)}(h+ h]h}(h]restructuredtextah ]h"]restructuredtextah$]h&]refurijuh1jDjKhjgubh* 文件转 换成漂亮的文档。使用 }(hjghhhNhNubj)}(h``make htmldocs``h]h make htmldocs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjgubh 或 }(hjghhhNhNubj)}(h``make pdfdocs``h]h make pdfdocs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjgubhF 命令即可构建HTML 或PDF格式的文档。生成的文档放在 }(hjghhhNhNubj)}(h``Documentation/output``h]hDocumentation/output}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjgubh 文件夹中。}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hjThhubh)}(hXreStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。 通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和 格式，但除此之外，它们还被作为reStructuredText处理。h]hXreStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。 通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和 格式，但除此之外，它们还被作为reStructuredText处理。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjThhubh)}(h最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移， 其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。h](h:最后，有成千上万的纯文本文档文件散布在 }(hjhhhNhNubj)}(h``Documentation``h]h Documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhu 里。随着时间推移， 其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjThhubjE)}(h.. _sphinx_install_zh:h]h}(h]h ]h"]h$]h&]jPsphinx-install-zhuh1jDhK#hjThhhhubeh}(h](jQid1eh ]h"](简介 sphinxdoc_zheh$]h&]uh1jRhhhhhhhK expect_referenced_by_name}jDjFsexpect_referenced_by_id}jQjFsubjS)}(hhh](jX)}(h 安装Sphinxh]h 安装Sphinx}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1jWhjKhhhhhKubh)}(hLDocumentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。h]hLDocumentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjKhhubh)}(hi这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 :ref:`sphinx-pre-install_zh` 。h](hI这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 }(hjjhhhNhNubh)}(h:ref:`sphinx-pre-install_zh`h]hinline)}(hjth]hsphinx-pre-install_zh}(hjxhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1jvhjrubah}(h]h ]h"]h$]h&]refdoc#translations/zh_CN/doc-guide/sphinx refdomainjreftyperef refexplicitrefwarn reftargetsphinx-pre-install_zhuh1hhhhKhjjubh 。}(hjjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjKhhubh)}(h大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它 或其他一些Python包导致文档构建中断的情况并不少见。h]h大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它 或其他一些Python包导致文档构建中断的情况并不少见。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hjKhhubh)}(h避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用 ``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境中安装Sphinx，具体取决于发行版 如何打包Python3。h](hd避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用 }(hjhhhNhNubj)}(h``virtualenv-3``h]h virtualenv-3}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 或 }(hjhhhNhNubj)}(h``virtualenv``h]h virtualenv}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhQ 在虚拟环境中安装Sphinx，具体取决于发行版 如何打包Python3。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK%hjKhhubh)}(hX5#) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 ``pip install sphinx_rtd_theme`` 单独安装。 #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX 编写的。它需要安装amsfonts和amsmath宏包，以便显示。h]henumerated_list)}(hhh](h list_item)}(h~html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 ``pip install sphinx_rtd_theme`` 单独安装。 h]h)}(h}html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 ``pip install sphinx_rtd_theme`` 单独安装。h](hMhtml输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 }(hjhhhNhNubj)}(h ``pip install sphinx_rtd_theme``h]hpip install sphinx_rtd_theme}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 单独安装。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK+hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX 编写的。它需要安装amsfonts和amsmath宏包，以便显示。h]h)}(h一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX 编写的。它需要安装amsfonts和amsmath宏包，以便显示。h]h一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX 编写的。它需要安装amsfonts和amsmath宏包，以便显示。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix)uh1jhjubah}(h]h ]h"]h$]h&]uh1hhjKhhhNhNubh)}(h8总之，如您要安装Sphinx 2.4.4版本，应执行::h]h7总之，如您要安装Sphinx 2.4.4版本，应执行:}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjKhhubh literal_block)}(h}$ virtualenv sphinx_2.4.4 $ . sphinx_2.4.4/bin/activate (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txth]h}$ virtualenv sphinx_2.4.4 $ . sphinx_2.4.4/bin/activate (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt}hjOsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jMhhhK3hjKhhubh)}(h在运行 ``. sphinx_2.4.4/bin/activate`` 之后，提示符将变化，以指示您正在使用新 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 次进入虚拟环境中。h](h 在运行 }(hj_hhhNhNubj)}(h``. sphinx_2.4.4/bin/activate``h]h. sphinx_2.4.4/bin/activate}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1jhj_ubh 之后，提示符将变化，以指示您正在使用新 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 次进入虚拟环境中。}(hj_hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK7hjKhhubjS)}(hhh](jX)}(h 图片输出h]h 图片输出}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhKhjubh ）。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK>hjhhubh)}(h为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包， 构建系统仍将构建文档，但不会在输出中包含任何图像。h]h为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包， 构建系统仍将构建文档，但不会在输出中包含任何图像。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjhhubeh}(h]id3ah ]h"] 图片输出ah$]h&]uh1jRhjKhhhhhK`_ 和 `reStructuredText `_ 的文档，以了解如何使用它们。 特别是Sphinx `reStructuredText 基础`_ 这是开始学习使用reStructuredText的 好地方。还有一些 `Sphinx 特殊标记结构`_ 。h](h 请参阅 }(hjKhhhNhNubj)}(h&`Sphinx `_h]hSphinx}(hjShhhNhNubah}(h]h ]h"]h$]h&]nameSphinxjhttp://www.sphinx-doc.org/uh1jhjKubjE)}(h h]h}(h]id8ah ]h"]h$]sphinxah&]refurijcuh1jDjKhjKubh 和 }(hjKhhhNhNubj)}(h>`reStructuredText `_h]hreStructuredText}(hjuhhhNhNubah}(h]h ]h"]h$]h&]namereStructuredTextj(http://docutils.sourceforge.net/rst.htmluh1jhjKubjE)}(h+ h]h}(h]id9ah ]h"]h$]restructuredtextah&]refurijuh1jDjKhjKubh< 的文档，以了解如何使用它们。 特别是Sphinx }(hjKhhhNhNubj)}(h`reStructuredText 基础`_h]hreStructuredText 基础}(hjhhhNhNubah}(h]h ]h"]h$]h&]namereStructuredText 基础j-http://www.sphinx-doc.org/en/stable/rest.htmluh1jhjKjKubhF 这是开始学习使用reStructuredText的 好地方。还有一些 }(hjKhhhNhNubj)}(h`Sphinx 特殊标记结构`_h]hSphinx 特殊标记结构}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameSphinx 特殊标记结构j5http://www.sphinx-doc.org/en/stable/markup/index.htmluh1jhjKjKubh 。}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjEhhubjE)}(hJ.. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.htmlh]h}(h]id10ah ]h"]restructuredtext 基础ah$]h&]jjuh1jDhKhjEhhhhjKubjE)}(hT.. _Sphinx 特殊标记结构: http://www.sphinx-doc.org/en/stable/markup/index.htmlh]h}(h]id11ah ]h"]sphinx 特殊标记结构ah$]h&]jjuh1jDhKhjEhhhhjKubjS)}(hhh](jX)}(h内核文档的具体指南h]h内核文档的具体指南}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhKubh)}(h*这是一些内核文档的具体指南：h]h*这是一些内核文档的具体指南：}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh bullet_list)}(hhh](j)}(h请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档 应该是纯文本，格式应足够一致，以便可以转换为其他格式。 h]h)}(h请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档 应该是纯文本，格式应足够一致，以便可以转换为其他格式。h]h请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档 应该是纯文本，格式应足够一致，以便可以转换为其他格式。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hM将现有文档转换为reStructuredText时，请尽量减少格式更改。 h]h)}(hL将现有文档转换为reStructuredText时，请尽量减少格式更改。h]hL将现有文档转换为reStructuredText时，请尽量减少格式更改。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hC在转换文档时，还要更新内容，而不仅仅是格式。 h]h)}(hB在转换文档时，还要更新内容，而不仅仅是格式。h]hB在转换文档时，还要更新内容，而不仅仅是格式。}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX请遵循标题修饰符的顺序： 1. ``=`` 文档标题，要有上线:: ======== 文档标题 ======== 2. ``=`` 章:: 章标题 ====== 3. ``-`` 节:: 节标题 ------ 4. ``~`` 小节:: 小节标题 ~~~~~~~~ 尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。 h](h)}(h$请遵循标题修饰符的顺序：h]h$请遵循标题修饰符的顺序：}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjKubj)}(hhh](j)}(hJ``=`` 文档标题，要有上线:: ======== 文档标题 ======== h](h)}(h#``=`` 文档标题，要有上线::h](j)}(h``=``h]h=}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjdubh 文档标题，要有上线:}(hjdhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj`ubjN)}(h======== 文档标题 ========h]h======== 文档标题 ========}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhKhj`ubeh}(h]h ]h"]h$]h&]uh1jhj]ubj)}(h"``=`` 章:: 章标题 ====== h](h)}(h ``=`` 章::h](j)}(h``=``h]h=}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 章:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubjN)}(h章标题 ======h]h章标题 ======}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhj]ubj)}(h"``-`` 节:: 节标题 ------ h](h)}(h ``-`` 节::h](j)}(h``-``h]h-}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 节:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubjN)}(h节标题 ------h]h节标题 ------}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhj]ubj)}(h*``~`` 小节:: 小节标题 ~~~~~~~~ h](h)}(h``~`` 小节::h](j)}(h``~``h]h~}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh 小节:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubjN)}(h小节标题 ~~~~~~~~h]h小节标题 ~~~~~~~~}hj sbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhj]ubeh}(h]h ]h"]h$]h&]j4j5j6hj7juh1jhjKubh)}(h尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。h]h尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。}(hj6 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjKubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX(对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不 大的内容，尤其是短代码段； ``.. code-block:: `` 用于需要语法高亮的 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。 h]h)}(hX&对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不 大的内容，尤其是短代码段； ``.. code-block:: `` 用于需要语法高亮的 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。h](hL对于插入固定宽度的文本块（用于代码样例、用例等）： }(hjN hhhNhNubj)}(h``::``h]h::}(hjV hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjN ubhE 用于语法高亮意义不 大的内容，尤其是短代码段； }(hjN hhhNhNubj)}(h``.. code-block:: ``h]h.. code-block:: }(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjN ubhq 用于需要语法高亮的 较长代码块。对于嵌入到文本中的简短代码片段，请使用 `` 。}(hjN hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjJ ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhjhhubeh}(h]id12ah ]h"]内核文档的具体指南ah$]h&]uh1jRhjEhhhhhKubjS)}(hhh](jX)}(hC域h]hC域}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhKubh)}(hW**Sphinx C域（Domain）** （name c）适用于C API文档。例如，函数原型：h](hstrong)}(h**Sphinx C域（Domain）**h]hSphinx C域（Domain）}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh< （name c）适用于C API文档。例如，函数原型：}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubjN)}(h0.. c:function:: int ioctl( int fd, int request )h]h0.. c:function:: int ioctl( int fd, int request )}hj sbah}(h]h ]h"]h$]h&]j]j^forcelanguagersthighlight_args}uh1jMhhhKhj hhubh)}(h内核文档的C域有一些附加特性。例如，您可以使用诸如 ``open`` 或 ``ioctl`` 这样的 通用名称重命名函数的引用名称：h](hJ内核文档的C域有一些附加特性。例如，您可以使用诸如 }(hj hhhNhNubj)}(h``open``h]hopen}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh 或 }(hj hhhNhNubj)}(h ``ioctl``h]hioctl}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh8 这样的 通用名称重命名函数的引用名称：}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubjN)}(hL.. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUSh]hL.. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUS}hj sbah}(h]h ]h"]h$]h&]j]j^j j rstj }uh1jMhhhKhj hhubh)}(h函数名称（例如ioctl）仍保留在输出中，但引用名称从 ``ioctl`` 变为 ``VIDIOC_LOG_STATUS`` 。此函数的索引项也变为 ``VIDIOC_LOG_STATUS`` 。h](hH函数名称（例如ioctl）仍保留在输出中，但引用名称从 }(hj hhhNhNubj)}(h ``ioctl``h]hioctl}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh 变为 }(hj hhhNhNubj)}(h``VIDIOC_LOG_STATUS``h]hVIDIOC_LOG_STATUS}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh# 。此函数的索引项也变为 }(hj hhhNhNubj)}(h``VIDIOC_LOG_STATUS``h]hVIDIOC_LOG_STATUS}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh 。}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX9请注意，不需要使用 ``c:func:`` 生成函数文档的交叉引用。由于一些Sphinx扩展的 神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 ``function()`` 的引用转换为交叉引用。如果在内核文档中看到 ``c:func:`` 的用法，请删除它。h](h请注意，不需要使用 }(hj^ hhhNhNubj)}(h ``c:func:``h]hc:func:}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj^ ubh 生成函数文档的交叉引用。由于一些Sphinx扩展的 神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 }(hj^ hhhNhNubj)}(h``function()``h]h function()}(hjx hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj^ ubhA 的引用转换为交叉引用。如果在内核文档中看到 }(hj^ hhhNhNubj)}(h ``c:func:``h]hc:func:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj^ ubh 的用法，请删除它。}(hj^ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]cah ]h"]c域ah$]h&]uh1jRhjEhhhhhKubjS)}(hhh](jX)}(h列表h]h列表}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhKubh)}(hX!我们建议使用 *列式表* 格式。 *列式表* 格式是二级列表。与ASCII艺术相比，它们对 文本文件的读者来说可能没有那么舒适。但其优点是易于创建或修改，而且修改的差异 （diff）更有意义，因为差异仅限于修改的内容。h](h我们建议使用 }(hj hhhNhNubhemphasis)}(h *列式表*h]h 列式表}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh 格式。 }(hj hhhNhNubj )}(h *列式表*h]h 列式表}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh 格式是二级列表。与ASCII艺术相比，它们对 文本文件的读者来说可能没有那么舒适。但其优点是易于创建或修改，而且修改的差异 （diff）更有意义，因为差异仅限于修改的内容。}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(h^*平铺表* 也是一个二级列表，类似于 *列式表* ，但具有一些额外特性：h](j )}(h *平铺表*h]h 平铺表}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh& 也是一个二级列表，类似于 }(hj hhhNhNubj )}(h *列式表*h]h 列式表}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh" ，但具有一些额外特性：}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj)}(hhh](j)}(hK列范围：使用 ``cspan`` 修饰，可以通过其他列扩展单元格 h]h)}(hJ列范围：使用 ``cspan`` 修饰，可以通过其他列扩展单元格h](h列范围：使用 }(hj$ hhhNhNubj)}(h ``cspan``h]hcspan}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj$ ubh. 修饰，可以通过其他列扩展单元格}(hj$ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hK行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格 h]h)}(hJ行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格h](h行范围：使用 }(hjN hhhNhNubj)}(h ``rspan``h]hrspan}(hjV hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjN ubh. 修饰，可以通过其他行扩展单元格}(hjN hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjJ ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hX 自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动 插入（空）单元格，而不是扩展合并到最后一个单元格。 h]h)}(hX自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动 插入（空）单元格，而不是扩展合并到最后一个单元格。h](h^自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 }(hjx hhhNhNubj)}(h``:fill-cells:``h]h :fill-cells:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjx ubh 选项，此行为可以从 }(hjx hhhNhNubj )}(h*自动合并*h]h 自动合并}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjx ubh 更改为 }(hjx hhhNhNubj )}(h*自动插入*h]h 自动插入}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjx ubhV ，自动 插入（空）单元格，而不是扩展合并到最后一个单元格。}(hjx hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjt ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhKhj hhubh)}(h 选项：h]h 选项：}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj)}(hhh](j)}(h)``:header-rows:`` [int] 标题行计数h]h)}(hj h](j)}(h``:header-rows:``h]h :header-rows:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh [int] 标题行计数}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(h)``:stub-columns:`` [int] 标题列计数h]h)}(hj h](j)}(h``:stub-columns:``h]h:stub-columns:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh [int] 标题列计数}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(h-``:widths:`` [[int] [int] ... ] 列宽h]h)}(hj% h](j)}(h ``:widths:``h]h:widths:}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj' ubh! [[int] [int] ... ] 列宽}(hj' hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj# ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hW``:fill-cells:`` 插入缺少的单元格，而不是自动合并缺少的单元格 h]h)}(hV``:fill-cells:`` 插入缺少的单元格，而不是自动合并缺少的单元格h](j)}(h``:fill-cells:``h]h :fill-cells:}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjL ubhF 插入缺少的单元格，而不是自动合并缺少的单元格}(hjL hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjH ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhKhj hhubh)}(h 修饰：h]h 修饰：}(hjt hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj)}(hhh](j)}(h``:cspan:`` [int] 扩展列h]h)}(hj h](j)}(h ``:cspan:``h]h:cspan:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh [int] 扩展列}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(h``:rspan:`` [int] 扩展行 h]h)}(h``:rspan:`` [int] 扩展行h](j)}(h ``:rspan:``h]h:rspan:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh [int] 扩展行}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhKhj hhubh)}(hX@下面的例子演示了如何使用这些标记。分级列表的第一级是 *表格行* 。 *表格行* 中 只允许一个标记，即该 *表格行* 中的单元格列表。 *comments* （ ``..`` ）和 *targets* 例外（例如引用 ``:ref:`最后一行 ``` / :ref:`最后一行 ` ）。h](hO下面的例子演示了如何使用这些标记。分级列表的第一级是 }(hj hhhNhNubj )}(h *表格行*h]h 表格行}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh 。 }(hj hhhNhNubj )}(h *表格行*h]h 表格行}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh$ 中 只允许一个标记，即该 }(hj hhhNhNubj )}(h *表格行*h]h 表格行}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh 中的单元格列表。 }(hj hhhNhNubj )}(h *comments*h]hcomments}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh （ }(hj hhhNhNubj)}(h``..``h]h..}(hj& hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh ）和 }(hj hhhNhNubj )}(h *targets*h]htargets}(hj8 hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh 例外（例如引用 }(hj hhhNhNubj)}(h%``:ref:`最后一行 ```h]h!:ref:`最后一行 `}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh / }(hj hhhNhNubh)}(h!:ref:`最后一行 `h]jw)}(hj^ h]h 最后一行}(hj` hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jvhj\ ubah}(h]h ]h"]h$]h&]refdocj refdomainjj reftyperef refexplicitrefwarnj last row_zhuh1hhhhKhj ubh ）。}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubjN)}(hX-.. flat-table:: 表格标题 :widths: 2 1 1 3 * - 表头 列1 - 表头 列2 - 表头 列3 - 表头 列4 * - 行1 - 字段1.1 - 字段1.2（自动扩展） * - 行2 - 字段2.1 - :rspan:`1` :cspan:`1` 字段2.2~3.3 * .. _`last row_zh`: - 行3h]hX-.. flat-table:: 表格标题 :widths: 2 1 1 3 * - 表头 列1 - 表头 列2 - 表头 列3 - 表头 列4 * - 行1 - 字段1.1 - 字段1.2（自动扩展） * - 行2 - 字段2.1 - :rspan:`1` :cspan:`1` 字段2.2~3.3 * .. _`last row_zh`: - 行3}hj sbah}(h]h ]h"]h$]h&]j]j^j j rstj }uh1jMhhhMhj hhubh)}(h渲染效果：h]h渲染效果：}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hX... flat-table:: 表格标题 :widths: 2 1 1 3 * - 表头 列1 - 表头 列2 - 表头 列3 - 表头 列4 * - 行1 - 字段1.1 - 字段1.2（自动扩展） * - 行2 - 字段2.1 - :rspan:`1` :cspan:`1` 字段2.2~3.3 * .. _`last row_zh`: - 行3 h]htable)}(hhh](jX)}(h 表格标题h]h 表格标题}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jWhhhMhj ubhtgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1j hj ubj )}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1j hj ubj )}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1j hj ubj )}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1j hj ubhtbody)}(hhh](hrow)}(hhh](hentry)}(hhh]h)}(h 表头 列1h]h 表头 列1}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh]h)}(h 表头 列2h]h 表头 列2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh]h)}(h 表头 列3h]h 表头 列3}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj$ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh]h)}(h 表头 列4h]h 表头 列4}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj;ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j )}(hhh]h)}(h行1h]h行1}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj[ubah}(h]h ]h"]h$]h&]uh1j hjXubj )}(hhh]h)}(h 字段1.1h]h 字段1.1}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM!hjrubah}(h]h ]h"]h$]h&]uh1j hjXubj )}(hhh]h)}(h字段1.2（自动扩展）h]h字段1.2（自动扩展）}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hjubah}(h]h ]h"]h$]h&]morecolsKuh1j hjXubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j )}(hhh]h)}(h行2h]h行2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh]h)}(h 字段2.1h]h 字段2.1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh]h)}(h#:rspan:`1` :cspan:`1` 字段2.2~3.3h](h }(hjhhhNhNubh 字段2.2~3.3}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM&hjubah}(h]h ]h"]h$]h&]morerowsKmorecolsKuh1j hjubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j )}(hhh](jE)}(h.. _`last row_zh`:h]h}(h]h ]h"]h$]h&]jP last-row-zhuh1jDhM3hjubh)}(h行3h]h行3}(hj hhhNhNubah}(h]j ah ]h"] last row_zhah$]h&]uh1hhhhM*hjjG}jjsjI}j jsubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh]h}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]colsKuh1j hj ubeh}(h]id16ah ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1jhhhMhj hhubeh}(h]id13ah ]h"]列表ah$]h&]uh1jRhjEhhhhhKubjS)}(hhh](jX)}(h 交叉引用h]h 交叉引用}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jWhjThhhhhM-ubh)}(hXX从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式 要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要 交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 ``.rst`` 扩展名是可选 的）::h](hX4从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式 要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要 交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 }(hjehhhNhNubj)}(h``.rst``h]h.rst}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjeubh 扩展名是可选 的）:}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM/hjThhubjN)}(h参见 Documentation/doc-guide/sphinx.rst 。此法始终可用。 请查看 sphinx.rst ，仅在同级目录中有效。 请阅读 ../sphinx.rst ，上级目录中的文件。h]h参见 Documentation/doc-guide/sphinx.rst 。此法始终可用。 请查看 sphinx.rst ，仅在同级目录中有效。 请阅读 ../sphinx.rst ，上级目录中的文件。}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhM4hjThhubh)}(h~如果要使用相对路径，则需要使用Sphinx的 ``doc`` 修饰。例如，从同一目录引用此页 的操作如下::h](h7如果要使用相对路径，则需要使用Sphinx的 }(hjhhhNhNubj)}(h``doc``h]hdoc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh? 修饰。例如，从同一目录引用此页 的操作如下:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM8hjThhubjN)}(h<参见 :doc:`sphinx文档的自定义链接文本 `.h]h<参见 :doc:`sphinx文档的自定义链接文本 `.}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhM;hjThhubh)}(h对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一 个没有任何特殊作用的 ``:doc:`` 用法，请将其转换为文档路径。h](h对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一 个没有任何特殊作用的 }(hjhhhNhNubj)}(h ``:doc:``h]h:doc:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh+ 用法，请将其转换为文档路径。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM=hjThhubh)}(hk有关交叉引用kernel-doc函数或类型的信息，请参阅 Documentation/doc-guide/kernel-doc.rst 。h]hk有关交叉引用kernel-doc函数或类型的信息，请参阅 Documentation/doc-guide/kernel-doc.rst 。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hjThhubjE)}(h.. _sphinx_kfigure_zh:h]h}(h]h ]h"]h$]h&]jPsphinx-kfigure-zhuh1jDhMNhjThhhhubeh}(h]id14ah ]h"] 交叉引用ah$]h&]uh1jRhjEhhhhhM-ubeh}(h]id6ah ]h"] 编写文档ah$]h&]uh1jRhhhhhhhKubjS)}(hhh](jX)}(h 图形图片h]h 图形图片}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhMFubh)}(h如果要添加图片，应该使用 ``kernel-figure`` 和 ``kernel-image`` 指令。例如， 要插入具有可缩放图像格式的图形，请使用SVG（:ref:`svg_image_example_zh` ）::h](h%如果要添加图片，应该使用 }(hjhhhNhNubj)}(h``kernel-figure``h]h kernel-figure}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 和 }(hjhhhNhNubj)}(h``kernel-image``h]h kernel-image}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhS 指令。例如， 要插入具有可缩放图像格式的图形，请使用SVG（}(hjhhhNhNubh)}(h:ref:`svg_image_example_zh`h]jw)}(hjIh]hsvg_image_example_zh}(hjKhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jvhjGubah}(h]h ]h"]h$]h&]refdocj refdomainjUreftyperef refexplicitrefwarnjsvg_image_example_zhuh1hhhhMHhjubh ）:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhj hhubjN)}(hg.. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: 简易 SVG 图片 SVG 图片示例h]hg.. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: 简易 SVG 图片 SVG 图片示例}hjqsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhMKhj hhubjE)}(h.. _svg_image_example_zh:h]h}(h]h ]h"]h$]h&]jPsvg-image-example-zhuh1jDhM[hj hhhhubkfigure kernel_figure)}(hhh]hfigure)}(hhh](himage)}(hh.. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: 简易 SVG 图片 SVG 图片示例 h]h}(h]h ]h"]h$]h&]alt简易 SVG 图片uridoc-guide/svg_image.svg candidates}j jsuh1jhjhhhKubhcaption)}(hSVG 图片示例h]hSVG 图片示例}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMUhjubeh}(h]id17ah ]h"]h$]h&]uh1jhjubah}(h]jah ]h"]svg_image_example_zhah$]h&]uh1jhj hhhhhNjG}jjsjI}jjsubh)}(hC内核figure（和image）指令支持 DOT 格式文件，请参阅h]hC内核figure（和image）指令支持 DOT 格式文件，请参阅}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhj hhubj)}(hhh](j)}(h*DOT：http://graphviz.org/pdf/dotguide.pdfh]h)}(hjh](hDOT：}(hjhhhNhNubj)}(h$http://graphviz.org/pdf/dotguide.pdfh]h$http://graphviz.org/pdf/dotguide.pdf}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMYhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h8Graphviz：http://www.graphviz.org/content/dot-language h]h)}(h7Graphviz：http://www.graphviz.org/content/dot-languageh](h Graphviz：}(hjhhhNhNubj)}(h,http://www.graphviz.org/content/dot-languageh]h,http://www.graphviz.org/content/dot-language}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurij uh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMZhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhMYhj hhubh)}(h6一个简单的例子（:ref:`hello_dot_file_zh` ）::h](h一个简单的例子（}(hj+hhhNhNubh)}(h:ref:`hello_dot_file_zh`h]jw)}(hj5h]hhello_dot_file_zh}(hj7hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jvhj3ubah}(h]h ]h"]h$]h&]refdocj refdomainjAreftyperef refexplicitrefwarnjhello_dot_file_zhuh1hhhhM\hj+ubh ）:}(hj+hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM\hj hhubjN)}(h[.. kernel-figure:: ../../../doc-guide/hello.dot :alt: 你好，世界 DOT 示例h]h[.. kernel-figure:: ../../../doc-guide/hello.dot :alt: 你好，世界 DOT 示例}hj]sbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhM^hj hhubjE)}(h.. _hello_dot_file_zh:h]h}(h]h ]h"]h$]h&]jPhello-dot-file-zhuh1jDhMnhj hhhhubj)}(hhh]j)}(hhh](j)}(h\.. kernel-figure:: ../../../doc-guide/hello.dot :alt: 你好，世界 DOT 示例 h]h}(h]h ]h"]h$]h&]alt你好，世界uridoc-guide/hello.dotj}j jsuh1jhjyhhhKubj)}(h DOT 示例h]h DOT 示例}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhhjyubeh}(h]id18ah ]h"]h$]h&]uh1jhjvubah}(h]juah ]h"]hello_dot_file_zhah$]h&]uh1jhj hhhhhNjG}jjksjI}jujksubh)}(hb嵌入的渲染标记（或语言），如Graphviz的 **DOT** 由 ``kernel-render`` 指令提供::h](h6嵌入的渲染标记（或语言），如Graphviz的 }(hjhhhNhNubj )}(h**DOT**h]hDOT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh 由 }(hjhhhNhNubj)}(h``kernel-render``h]h kernel-render}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 指令提供:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMjhj hhubjN)}(h.. kernel-render:: DOT :alt: 有向图 :caption: 嵌入式 **DOT** (Graphviz) 代码 digraph foo { "五棵松" -> "国贸"; }h]h.. kernel-render:: DOT :alt: 有向图 :caption: 嵌入式 **DOT** (Graphviz) 代码 digraph foo { "五棵松" -> "国贸"; }}hjsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhMlhj hhubh)}(h如何渲染取决于安装的工具。如果安装了Graphviz，您将看到一个矢量图像。否则，原始 标记将作为 *文字块* 插入（:ref:`hello_dot_render_zh` ）。h](h如何渲染取决于安装的工具。如果安装了Graphviz，您将看到一个矢量图像。否则，原始 标记将作为 }(hjhhhNhNubj )}(h *文字块*h]h 文字块}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh 插入（}(hjhhhNhNubh)}(h:ref:`hello_dot_render_zh`h]jw)}(hjh]hhello_dot_render_zh}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jvhjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftyperef refexplicitrefwarnjhello_dot_render_zhuh1hhhhMthjubh ）。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMthj hhubjE)}(h.. _hello_dot_render_zh:h]h}(h]h ]h"]h$]h&]jPhello-dot-render-zhuh1jDhMhj hhhhubj)}(hhh](j kernel_render)}(hhh]jN)}(h+digraph foo { "五棵松" -> "国贸"; }h]h+digraph foo { "五棵松" -> "国贸"; }}hj@sbah}(h]h ]h"]h$]h&]j]j^uh1jMhj=hhubah}(h]h ]h"]h$]h&]alt 有向图srclangDOTuh1j;hj8ubj)}(h#嵌入式 **DOT** (Graphviz) 代码h](h 嵌入式 }(hjXhhhNhNubj )}(h**DOT**h]hDOT}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjXubh (Graphviz) 代码}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj8ubeh}(h](id19j7eh ]h"]hello_dot_render_zhah$]h&]altjUcaptionjZuh1jhj hhhhhNjG}j}j-sjI}j7j-subh)}(hX*render* 指令包含 *figure* 指令中已知的所有选项，以及选项 ``caption`` 。如果 ``caption`` 有值，则插入一个 *figure* 节点，若无，则插入一个 *image* 节点。 如果您想引用它，还需要一个 ``caption`` （:ref:`hello_svg_render_zh` ）。h](j )}(h*render*h]hrender}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh 指令包含 }(hjhhhNhNubj )}(h*figure*h]hfigure}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh/ 指令中已知的所有选项，以及选项 }(hjhhhNhNubj)}(h ``caption``h]hcaption}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 。如果 }(hjhhhNhNubj)}(h ``caption``h]hcaption}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 有值，则插入一个 }(hjhhhNhNubj )}(h*figure*h]hfigure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh# 节点，若无，则插入一个 }(hjhhhNhNubj )}(h*image*h]himage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh3 节点。 如果您想引用它，还需要一个 }(hjhhhNhNubj)}(h ``caption``h]hcaption}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh （}(hjhhhNhNubh)}(h:ref:`hello_svg_render_zh`h]jw)}(hjh]hhello_svg_render_zh}(hj hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jvhjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftyperef refexplicitrefwarnjhello_svg_render_zhuh1hhhhMhjubh ）。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h嵌入式 **SVG**::h](h 嵌入式 }(hj0hhhNhNubj )}(h**SVG**h]hSVG}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj0ubh:}(hj0hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubjN)}(h.. kernel-render:: SVG :caption: 嵌入式 **SVG** 标记 :alt: 右上箭头 ... h]h.. kernel-render:: SVG :caption: 嵌入式 **SVG** 标记 :alt: 右上箭头 ... }hjPsbah}(h]h ]h"]h$]h&]j]j^uh1jMhhhMhj hhubjE)}(h.. _hello_svg_render_zh:h]h}(h]h ]h"]h$]h&]jPhello-svg-render-zhuh1jDhMhj hhhhubj)}(hhh](j<)}(hhh]jN)}(hX? h]hX? }hjosbah}(h]h ]h"]h$]h&]j]j^uh1jMhjlhhubah}(h]h ]h"]h$]h&]jT 右上箭头jVSVGuh1j;hjiubj)}(h嵌入式 **SVG** 标记h](h 嵌入式 }(hjhhhNhNubj )}(h**SVG**h]hSVG}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh 标记}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjiubeh}(h](id20jheh ]h"]hello_svg_render_zhah$]h&]captionjaltjuh1jhj hhhhhNjG}jj^sjI}jhj^subeh}(h](jid15eh ]h"]( 图形图片sphinx_kfigure_zheh$]h&]uh1jRhhhhhhhMFjG}jjsjI}jjsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(jWN generatorN datestampN source_linkN source_urlN toc_backlinksj footnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh، _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}( 主目录树]jarestructuredtext 基础]jasphinx 特殊标记结构]jaurefids}(jQ]jFaj=]j3ajS]jIaj ]jaj]jaj]jaju]jkaj7]j-ajh]j^aunameids}(jDjQjCj@jjjjjj=jjjjjYjVj jSj jjBj?jjjjjjjjj j j j jQjNjj jjjjjjjjjjuj}j7jjhu nametypes}(jDjCjjjjjjYj j jBjjjjj j jQjjjjjjj}juh}(jQjTj@jTjjjjj=jKjjKjjjVjjSj\jj\j?jjjEjjjjjdjjjjjjj jj j jNj j j jjTjj jj jjjujvj7j8jhjijAj jjjjyjzj8jjiu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jKsRparse_messages](hsystem_message)}(hhh]h)}(h)Duplicate explicit target name: "sphinx".h]h-Duplicate explicit target name: “sphinx”.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQubah}(h]h ]h"]h$]h&]jjalevelKtypeINFOsourceh،lineKuh1jOhjEhhhhhKubjP)}(hhh]h)}(h3Duplicate explicit target name: "restructuredtext".h]h7Duplicate explicit target name: “restructuredtext”.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjmubah}(h]h ]h"]h$]h&]jalevelKtypejjsourceh،lineKuh1jOhjEhhhhhKubetransform_messages](jP)}(hhh]h)}(hhh]h2Hyperlink target "sphinxdoc-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineKuh1jOubjP)}(hhh]h)}(hhh]h7Hyperlink target "sphinx-install-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineK#uh1jOubjP)}(hhh]h)}(hhh]h;Hyperlink target "sphinx-pre-install-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineKZuh1jOubjP)}(hhh]h)}(hhh]h1Hyperlink target "last-row-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejjlineM(sourcehuh1jOubjP)}(hhh]h)}(hhh]h7Hyperlink target "sphinx-kfigure-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineMNuh1jOubjP)}(hhh]h)}(hhh]h:Hyperlink target "svg-image-example-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineM[uh1jOubjP)}(hhh]h)}(hhh]h7Hyperlink target "hello-dot-file-zh" is not referenced.}hj)sbah}(h]h ]h"]h$]h&]uh1hhj&ubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineMnuh1jOubjP)}(hhh]h)}(hhh]h9Hyperlink target "hello-dot-render-zh" is not referenced.}hjCsbah}(h]h ]h"]h$]h&]uh1hhj@ubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineMuh1jOubjP)}(hhh]h)}(hhh]h9Hyperlink target "hello-svg-render-zh" is not referenced.}hj]sbah}(h]h ]h"]h$]h&]uh1hhjZubah}(h]h ]h"]h$]h&]levelKtypejjsourceh،lineMuh1jOube transformerN include_log]5Documentation/translations/zh_CN/doc-guide/sphinx.rst(NNNNta decorationNhhub.