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]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget$/translations/pt_BR/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译者}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhKubh)}(h*吴想成 Wu XiangCheng h]h)}(h)吴想成 Wu XiangCheng h](h吴想成 Wu XiangCheng <}(hj"hhhNhNubh reference)}(hbobwxc@email.cnh]hbobwxc@email.cn}(hj,hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:bobwxc@email.cnuh1j*hj"ubh>}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhj ubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]h ]h"]h$]h&]uh1hhhhhhhhKubhtarget)}(h.. _sphinxdoc_zh:h]h}(h]h ]h"]h$]h&]refid sphinxdoc-zhuh1jXhKhhhhhhubhsection)}(hhh](htitle)}(h简介h]h简介}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhjhhhhhhK ubh)}(hXULinux内核使用 `Sphinx `_ 来把 ``Documentation`` 下的 `reStructuredText `_ 文件转 换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML 或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。h](hLinux内核使用 }(hj{hhhNhNubj+)}(h&`Sphinx `_h]hSphinx}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameSphinxrefurihttp://www.sphinx-doc.org/uh1j*hj{ubjY)}(h h]h}(h]sphinxah ]h"]sphinxah$]h&]refurijuh1jX referencedKhj{ubh 来把 }(hj{hhhNhNubhliteral)}(h``Documentation``h]h Documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj{ubh 下的 }(hj{hhhNhNubj+)}(h>`reStructuredText `_h]hreStructuredText}(hjhhhNhNubah}(h]h ]h"]h$]h&]namereStructuredTextj(http://docutils.sourceforge.net/rst.htmluh1j*hj{ubjY)}(h+ h]h}(h]restructuredtextah ]h"]restructuredtextah$]h&]refurijuh1jXjKhj{ubh* 文件转 换成漂亮的文档。使用 }(hj{hhhNhNubj)}(h``make htmldocs``h]h make htmldocs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj{ubh 或 }(hj{hhhNhNubj)}(h``make pdfdocs``h]h make pdfdocs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj{ubhF 命令即可构建HTML 或PDF格式的文档。生成的文档放在 }(hj{hhhNhNubj)}(h``Documentation/output``h]hDocumentation/output}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj{ubh 文件夹中。}(hj{hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hjhhhubh)}(hXreStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。 通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和 格式，但除此之外，它们还被作为reStructuredText处理。h]hXreStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。 通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和 格式，但除此之外，它们还被作为reStructuredText处理。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(h最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移， 其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。h](h:最后，有成千上万的纯文本文档文件散布在 }(hj'hhhNhNubj)}(h``Documentation``h]h Documentation}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj'ubhu 里。随着时间推移， 其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。}(hj'hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubjY)}(h.. _sphinx_install_zh:h]h}(h]h ]h"]h$]h&]jdsphinx-install-zhuh1jXhK#hjhhhhhubeh}(h](jeid1eh ]h"](简介 sphinxdoc_zheh$]h&]uh1jfhhhhhhhK expect_referenced_by_name}jXjZsexpect_referenced_by_id}jejZsubjg)}(hhh](jl)}(h 安装Sphinxh]h 安装Sphinx}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhj_hhhhhKubh)}(hLDocumentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。h]hLDocumentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj_hhubh)}(hi这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 :ref:`sphinx-pre-install_zh` 。h](hI这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 }(hj~hhhNhNubh)}(h:ref:`sphinx-pre-install_zh`h]hinline)}(hjh]hsphinx-pre-install_zh}(hjhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdoc#translations/zh_CN/doc-guide/sphinx refdomainjreftyperef refexplicitrefwarn reftargetsphinx-pre-install_zhuh1hhhhKhj~ubh 。}(hj~hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj_hhubh)}(h大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它 或其他一些Python包导致文档构建中断的情况并不少见。h]h大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它 或其他一些Python包导致文档构建中断的情况并不少见。}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hj_hhubh)}(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%hj_hhubh)}(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}(hj hhhNhNubah}(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宏包，以便显示。}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hj*ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix)uh1jhjubah}(h]h ]h"]h$]h&]uh1hhj_hhhNhNubh)}(h8总之，如您要安装Sphinx 2.4.4版本，应执行::h]h7总之，如您要安装Sphinx 2.4.4版本，应执行:}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hj_hhubh 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}hjcsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jahhhK3hj_hhubh)}(h在运行 ``. sphinx_2.4.4/bin/activate`` 之后，提示符将变化，以指示您正在使用新 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 次进入虚拟环境中。h](h 在运行 }(hjshhhNhNubj)}(h``. sphinx_2.4.4/bin/activate``h]h. sphinx_2.4.4/bin/activate}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjsubh 之后，提示符将变化，以指示您正在使用新 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 次进入虚拟环境中。}(hjshhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK7hj_hhubjg)}(hhh](jl)}(h 图片输出h]h 图片输出}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhjhhhhhKhjubh ）。}(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&]uh1jfhj_hhhhhK`_ 和 `reStructuredText `_ 的文档，以了解如何使用它们。 特别是Sphinx `reStructuredText 基础`_ 这是开始学习使用reStructuredText的 好地方。还有一些 `Sphinx 特殊标记结构`_ 。h](h 请参阅 }(hj_hhhNhNubj+)}(h&`Sphinx `_h]hSphinx}(hjghhhNhNubah}(h]h ]h"]h$]h&]nameSphinxjhttp://www.sphinx-doc.org/uh1j*hj_ubjY)}(h h]h}(h]id8ah ]h"]h$]sphinxah&]refurijwuh1jXjKhj_ubh 和 }(hj_hhhNhNubj+)}(h>`reStructuredText `_h]hreStructuredText}(hjhhhNhNubah}(h]h ]h"]h$]h&]namereStructuredTextj(http://docutils.sourceforge.net/rst.htmluh1j*hj_ubjY)}(h+ h]h}(h]id9ah ]h"]h$]restructuredtextah&]refurijuh1jXjKhj_ubh< 的文档，以了解如何使用它们。 特别是Sphinx }(hj_hhhNhNubj+)}(h`reStructuredText 基础`_h]hreStructuredText 基础}(hjhhhNhNubah}(h]h ]h"]h$]h&]namereStructuredText 基础j-http://www.sphinx-doc.org/en/stable/rest.htmluh1j*hj_jKubhF 这是开始学习使用reStructuredText的 好地方。还有一些 }(hj_hhhNhNubj+)}(h`Sphinx 特殊标记结构`_h]hSphinx 特殊标记结构}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameSphinx 特殊标记结构j5http://www.sphinx-doc.org/en/stable/markup/index.htmluh1j*hj_jKubh 。}(hj_hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjYhhubjY)}(hJ.. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.htmlh]h}(h]id10ah ]h"]restructuredtext 基础ah$]h&]jjuh1jXhKhjYhhhhjKubjY)}(hT.. _Sphinx 特殊标记结构: http://www.sphinx-doc.org/en/stable/markup/index.htmlh]h}(h]id11ah ]h"]sphinx 特殊标记结构ah$]h&]jjuh1jXhKhjYhhhhjKubjg)}(hhh](jl)}(h内核文档的具体指南h]h内核文档的具体指南}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhjhhhhhKubh)}(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时，请尽量减少格式更改。}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj/ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hC在转换文档时，还要更新内容，而不仅仅是格式。 h]h)}(hB在转换文档时，还要更新内容，而不仅仅是格式。h]hB在转换文档时，还要更新内容，而不仅仅是格式。}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjGubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX请遵循标题修饰符的顺序： 1. ``=`` 文档标题，要有上线:: ======== 文档标题 ======== 2. ``=`` 章:: 章标题 ====== 3. ``-`` 节:: 节标题 ------ 4. ``~`` 小节:: 小节标题 ~~~~~~~~ 尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。 h](h)}(h$请遵循标题修饰符的顺序：h]h$请遵循标题修饰符的顺序：}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj_ubj)}(hhh](j)}(hJ``=`` 文档标题，要有上线:: ======== 文档标题 ======== h](h)}(h#``=`` 文档标题，要有上线::h](j)}(h``=``h]h=}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjxubh 文档标题，要有上线:}(hjxhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjtubjb)}(h======== 文档标题 ========h]h======== 文档标题 ========}hjsbah}(h]h ]h"]h$]h&]jqjruh1jahhhKhjtubeh}(h]h ]h"]h$]h&]uh1jhjqubj)}(h"``=`` 章:: 章标题 ====== h](h)}(h ``=`` 章::h](j)}(h``=``h]h=}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 章:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubjb)}(h章标题 ======h]h章标题 ======}hjsbah}(h]h ]h"]h$]h&]jqjruh1jahhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjqubj)}(h"``-`` 节:: 节标题 ------ h](h)}(h ``-`` 节::h](j)}(h``-``h]h-}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 节:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubjb)}(h节标题 ------h]h节标题 ------}hjsbah}(h]h ]h"]h$]h&]jqjruh1jahhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjqubj)}(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&]uh1hhhhKhj ubjb)}(h小节标题 ~~~~~~~~h]h小节标题 ~~~~~~~~}hj0 sbah}(h]h ]h"]h$]h&]jqjruh1jahhhKhj ubeh}(h]h ]h"]h$]h&]uh1jhjqubeh}(h]h ]h"]h$]h&]jHjIjJhjKjuh1jhj_ubh)}(h尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。h]h尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj_ubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX(对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不 大的内容，尤其是短代码段； ``.. code-block:: `` 用于需要语法高亮的 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。 h]h)}(hX&对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不 大的内容，尤其是短代码段； ``.. code-block:: `` 用于需要语法高亮的 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。h](hL对于插入固定宽度的文本块（用于代码样例、用例等）： }(hjb hhhNhNubj)}(h``::``h]h::}(hjj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjb ubhE 用于语法高亮意义不 大的内容，尤其是短代码段； }(hjb hhhNhNubj)}(h``.. code-block:: ``h]h.. code-block:: }(hj| hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjb ubhq 用于需要语法高亮的 较长代码块。对于嵌入到文本中的简短代码片段，请使用 `` 。}(hjb hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj^ ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhjhhubeh}(h]id12ah ]h"]内核文档的具体指南ah$]h&]uh1jfhjYhhhhhKubjg)}(hhh](jl)}(hC域h]hC域}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jkhj 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 hhubjb)}(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&]jqjrforcelanguagersthighlight_args}uh1jahhhKhj 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 hhubjb)}(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&]jqjrj j rstj }uh1jahhhKhj hhubh)}(h函数名称（例如ioctl）仍保留在输出中，但引用名称从 ``ioctl`` 变为 ``VIDIOC_LOG_STATUS`` 。此函数的索引项也变为 ``VIDIOC_LOG_STATUS`` 。h](hH函数名称（例如ioctl）仍保留在输出中，但引用名称从 }(hj. hhhNhNubj)}(h ``ioctl``h]hioctl}(hj6 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj. ubh 变为 }(hj. hhhNhNubj)}(h``VIDIOC_LOG_STATUS``h]hVIDIOC_LOG_STATUS}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj. ubh# 。此函数的索引项也变为 }(hj. hhhNhNubj)}(h``VIDIOC_LOG_STATUS``h]hVIDIOC_LOG_STATUS}(hjZ 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请注意，不需要使用 }(hjr hhhNhNubj)}(h ``c:func:``h]hc:func:}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjr ubh 生成函数文档的交叉引用。由于一些Sphinx扩展的 神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 }(hjr hhhNhNubj)}(h``function()``h]h function()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjr ubhA 的引用转换为交叉引用。如果在内核文档中看到 }(hjr hhhNhNubj)}(h ``c:func:``h]hc:func:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjr ubh 的用法，请删除它。}(hjr hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]cah ]h"]c域ah$]h&]uh1jfhjYhhhhhKubjg)}(hhh](jl)}(h列表h]h列表}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jkhj 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列范围：使用 }(hj8 hhhNhNubj)}(h ``cspan``h]hcspan}(hj@ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8 ubh. 修饰，可以通过其他列扩展单元格}(hj8 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj4 ubah}(h]h ]h"]h$]h&]uh1jhj1 hhhhhNubj)}(hK行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格 h]h)}(hJ行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格h](h行范围：使用 }(hjb hhhNhNubj)}(h ``rspan``h]hrspan}(hjj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjb ubh. 修饰，可以通过其他行扩展单元格}(hjb hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj^ ubah}(h]h ]h"]h$]h&]uh1jhj1 hhhhhNubj)}(hX 自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动 插入（空）单元格，而不是扩展合并到最后一个单元格。 h]h)}(hX自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动 插入（空）单元格，而不是扩展合并到最后一个单元格。h](h^自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 }(hj hhhNhNubj)}(h``:fill-cells:``h]h :fill-cells:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj 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 ubhV ，自动 插入（空）单元格，而不是扩展合并到最后一个单元格。}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj1 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)}(hj9 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&]uh1hhhhKhj7 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:}(hjd hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj` ubhF 插入缺少的单元格，而不是自动合并缺少的单元格}(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)}(h 修饰：h]h 修饰：}(hj 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}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh 例外（例如引用 }(hj hhhNhNubj)}(h%``:ref:`最后一行 ```h]h!:ref:`最后一行 `}(hj^ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh / }(hj hhhNhNubh)}(h!:ref:`最后一行 `h]j)}(hjr h]h 最后一行}(hjt hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjp ubah}(h]h ]h"]h$]h&]refdocj refdomainj~ reftyperef refexplicitrefwarnj last row_zhuh1hhhhKhj ubh ）。}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubjb)}(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&]jqjrj j rstj }uh1jahhhMhj 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](jl)}(h 表格标题h]h 表格标题}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jkhhhMhj 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&]uh1jhjubj )}(hhh]h)}(h 表头 列2h]h 表头 列2}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj!ubah}(h]h ]h"]h$]h&]uh1jhjubj )}(hhh]h)}(h 表头 列3h]h 表头 列3}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj8ubah}(h]h ]h"]h$]h&]uh1jhjubj )}(hhh]h)}(h 表头 列4h]h 表头 列4}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjOubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j )}(hhh]h)}(h行1h]h行1}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjoubah}(h]h ]h"]h$]h&]uh1jhjlubj )}(hhh]h)}(h 字段1.1h]h 字段1.1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM!hjubah}(h]h ]h"]h$]h&]uh1jhjlubj )}(hhh]h)}(h字段1.2（自动扩展）h]h字段1.2（自动扩展）}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hjubah}(h]h ]h"]h$]h&]morecolsKuh1jhjlubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j )}(hhh]h)}(h行2h]h行2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hjubah}(h]h ]h"]h$]h&]uh1jhjubj )}(hhh]h)}(h 字段2.1h]h 字段2.1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjubah}(h]h ]h"]h$]h&]uh1jhjubj )}(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&]morerowsKmorecolsKuh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j )}(hhh](jY)}(h.. _`last row_zh`:h]h}(h]h ]h"]h$]h&]jd last-row-zhuh1jXhM3hjubh)}(h行3h]h行3}(hj hhhNhNubah}(h]jah ]h"] last row_zhah$]h&]uh1hhhhM*hjj[}j,jsj]}jjsubeh}(h]h ]h"]h$]h&]uh1jhjubj )}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(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&]uh1jfhjYhhhhhKubjg)}(hhh](jl)}(h 交叉引用h]h 交叉引用}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhjhhhhhhM-ubh)}(hXX从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式 要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要 交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 ``.rst`` 扩展名是可选 的）::h](hX4从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式 要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要 交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 }(hjyhhhNhNubj)}(h``.rst``h]h.rst}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjyubh 扩展名是可选 的）:}(hjyhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM/hjhhhubjb)}(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&]jqjruh1jahhhM4hjhhhubh)}(h~如果要使用相对路径，则需要使用Sphinx的 ``doc`` 修饰。例如，从同一目录引用此页 的操作如下::h](h7如果要使用相对路径，则需要使用Sphinx的 }(hjhhhNhNubj)}(h``doc``h]hdoc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh? 修饰。例如，从同一目录引用此页 的操作如下:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM8hjhhhubjb)}(h<参见 :doc:`sphinx文档的自定义链接文本 `.h]h<参见 :doc:`sphinx文档的自定义链接文本 `.}hjsbah}(h]h ]h"]h$]h&]jqjruh1jahhhM;hjhhhubh)}(h对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一 个没有任何特殊作用的 ``:doc:`` 用法，请将其转换为文档路径。h](h对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一 个没有任何特殊作用的 }(hjhhhNhNubj)}(h ``:doc:``h]h:doc:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh+ 用法，请将其转换为文档路径。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM=hjhhhubh)}(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@hjhhhubjY)}(h.. _sphinx_kfigure_zh:h]h}(h]h ]h"]h$]h&]jdsphinx-kfigure-zhuh1jXhMNhjhhhhhubeh}(h]id14ah ]h"] 交叉引用ah$]h&]uh1jfhjYhhhhhM-ubeh}(h]id6ah ]h"] 编写文档ah$]h&]uh1jfhhhhhhhKubjg)}(hhh](jl)}(h 图形图片h]h 图形图片}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1jkhjhhhhhMFubh)}(h如果要添加图片，应该使用 ``kernel-figure`` 和 ``kernel-image`` 指令。例如， 要插入具有可缩放图像格式的图形，请使用SVG（:ref:`svg_image_example_zh` ）::h](h%如果要添加图片，应该使用 }(hj/hhhNhNubj)}(h``kernel-figure``h]h kernel-figure}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj/ubh 和 }(hj/hhhNhNubj)}(h``kernel-image``h]h kernel-image}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj/ubhS 指令。例如， 要插入具有可缩放图像格式的图形，请使用SVG（}(hj/hhhNhNubh)}(h:ref:`svg_image_example_zh`h]j)}(hj]h]hsvg_image_example_zh}(hj_hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhj[ubah}(h]h ]h"]h$]h&]refdocj refdomainjireftyperef refexplicitrefwarnjsvg_image_example_zhuh1hhhhMHhj/ubh ）:}(hj/hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhjhhubjb)}(hg.. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: 简易 SVG 图片 SVG 图片示例h]hg.. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: 简易 SVG 图片 SVG 图片示例}hjsbah}(h]h ]h"]h$]h&]jqjruh1jahhhMKhjhhubjY)}(h.. _svg_image_example_zh:h]h}(h]h ]h"]h$]h&]jdsvg-image-example-zhuh1jXhM[hjhhhhubkfigure 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&]uh1jhjhhhhhNj[}jjsj]}jjsubh)}(hC内核figure（和image）指令支持 DOT 格式文件，请参阅h]hC内核figure（和image）指令支持 DOT 格式文件，请参阅}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhjhhubj)}(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&]refurijuh1j*hjubeh}(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}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurij uh1j*hjubeh}(h]h ]h"]h$]h&]uh1hhhhMZhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhMYhjhhubh)}(h6一个简单的例子（:ref:`hello_dot_file_zh` ）::h](h一个简单的例子（}(hj?hhhNhNubh)}(h:ref:`hello_dot_file_zh`h]j)}(hjIh]hhello_dot_file_zh}(hjKhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjGubah}(h]h ]h"]h$]h&]refdocj refdomainjUreftyperef refexplicitrefwarnjhello_dot_file_zhuh1hhhhM\hj?ubh ）:}(hj?hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM\hjhhubjb)}(h[.. kernel-figure:: ../../../doc-guide/hello.dot :alt: 你好，世界 DOT 示例h]h[.. kernel-figure:: ../../../doc-guide/hello.dot :alt: 你好，世界 DOT 示例}hjqsbah}(h]h ]h"]h$]h&]jqjruh1jahhhM^hjhhubjY)}(h.. _hello_dot_file_zh:h]h}(h]h ]h"]h$]h&]jdhello-dot-file-zhuh1jXhMnhjhhhhubj)}(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 jsuh1jhjhhhKubj)}(h DOT 示例h]h DOT 示例}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhhjubeh}(h]id18ah ]h"]h$]h&]uh1jhjubah}(h]jah ]h"]hello_dot_file_zhah$]h&]uh1jhjhhhhhNj[}jjsj]}jjsubh)}(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&]uh1hhhhMjhjhhubjb)}(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&]jqjruh1jahhhMlhjhhubh)}(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]j)}(hjh]hhello_dot_render_zh}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj refdomainj%reftyperef refexplicitrefwarnjhello_dot_render_zhuh1hhhhMthjubh ）。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMthjhhubjY)}(h.. _hello_dot_render_zh:h]h}(h]h ]h"]h$]h&]jdhello-dot-render-zhuh1jXhMhjhhhhubj)}(hhh](j kernel_render)}(hhh]jb)}(h+digraph foo { "五棵松" -> "国贸"; }h]h+digraph foo { "五棵松" -> "国贸"; }}hjTsbah}(h]h ]h"]h$]h&]jqjruh1jahjQhhubah}(h]h ]h"]h$]h&]alt 有向图srclangDOTuh1jOhjLubj)}(h#嵌入式 **DOT** (Graphviz) 代码h](h 嵌入式 }(hjlhhhNhNubj )}(h**DOT**h]hDOT}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1j hjlubh (Graphviz) 代码}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjLubeh}(h](id19jKeh ]h"]hello_dot_render_zhah$]h&]altjicaptionjnuh1jhjhhhhhNj[}jjAsj]}jKjAsubh)}(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}(hjhhhNhNubah}(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]j)}(hjh]hhello_svg_render_zh}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj refdomainj(reftyperef refexplicitrefwarnjhello_svg_render_zhuh1hhhhMhjubh ）。}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h嵌入式 **SVG**::h](h 嵌入式 }(hjDhhhNhNubj )}(h**SVG**h]hSVG}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjDubh:}(hjDhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjb)}(h.. kernel-render:: SVG :caption: 嵌入式 **SVG** 标记 :alt: 右上箭头 ... h]h.. kernel-render:: SVG :caption: 嵌入式 **SVG** 标记 :alt: 右上箭头 ... }hjdsbah}(h]h ]h"]h$]h&]jqjruh1jahhhMhjhhubjY)}(h.. _hello_svg_render_zh:h]h}(h]h ]h"]h$]h&]jdhello-svg-render-zhuh1jXhMhjhhhhubj)}(hhh](jP)}(hhh]jb)}(hX? h]hX? }hjsbah}(h]h ]h"]h$]h&]jqjruh1jahjhhubah}(h]h ]h"]h$]h&]jh 右上箭头jjSVGuh1jOhj}ubj)}(h嵌入式 **SVG** 标记h](h 嵌入式 }(hjhhhNhNubj )}(h**SVG**h]hSVG}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh 标记}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj}ubeh}(h](id20j|eh ]h"]hello_svg_render_zhah$]h&]captionjaltjuh1jhjhhhhhNj[}jjrsj]}j|jrsubeh}(h](j id15eh ]h"]( 图形图片sphinx_kfigure_zheh$]h&]uh1jfhhhhhhhMFj[}jjsj]}j jsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(jkN generatorN datestampN source_linkN source_urlN toc_backlinksjfootnote_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}(je]jZajQ]jGajg]j]aj]jaj ]jaj]jaj]jajK]jAaj|]jraunameids}(jXjejWjTjjjjj*jQj)j&jjjmjjjjgjjjVjSjjjjjjjjj j j j jejbj,jjjjj jjjjjjjjKjj|u nametypes}(jXjWjjj*j)jjmjjjVjjjjj j jej,jjjjjjjuh}(jejhjTjhjjjjjQj_j&j_jjjjjjgjpjjpjSj/jjYjjj~jxjjjjjjj jj j jbj jj jjhj jjjjjjjjKjLj|j}jUj jjjjjjLjj}u 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”.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjeubah}(h]h ]h"]h$]h&]j~alevelKtypeINFOsourcehlineKuh1jchjYhhhhhKubjd)}(hhh]h)}(h3Duplicate explicit target name: "restructuredtext".h]h7Duplicate explicit target name: “restructuredtext”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jalevelKtypej~sourcehlineKuh1jchjYhhhhhKubetransform_messages](jd)}(hhh]h)}(hhh]h2Hyperlink target "sphinxdoc-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej~sourcehlineKuh1jcubjd)}(hhh]h)}(hhh]h7Hyperlink target "sphinx-install-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej~sourcehlineK#uh1jcubjd)}(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&]levelKtypej~sourcehlineKZuh1jcubjd)}(hhh]h)}(hhh]h1Hyperlink target "last-row-zh" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej~lineM(sourcehuh1jcubjd)}(hhh]h)}(hhh]h7Hyperlink target "sphinx-kfigure-zh" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej~sourcehlineMNuh1jcubjd)}(hhh]h)}(hhh]h:Hyperlink target "svg-image-example-zh" is not referenced.}hj#sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej~sourcehlineM[uh1jcubjd)}(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&]levelKtypej~sourcehlineMnuh1jcubjd)}(hhh]h)}(hhh]h9Hyperlink target "hello-dot-render-zh" is not referenced.}hjWsbah}(h]h ]h"]h$]h&]uh1hhjTubah}(h]h ]h"]h$]h&]levelKtypej~sourcehlineMuh1jcubjd)}(hhh]h)}(hhh]h9Hyperlink target "hello-svg-render-zh" is not referenced.}hjqsbah}(h]h ]h"]h$]h&]uh1hhjnubah}(h]h ]h"]h$]h&]levelKtypej~sourcehlineMuh1jcube transformerN include_log]5Documentation/translations/zh_CN/doc-guide/sphinx.rst(NNNNta decorationNhhub.