重新构造文本初级读物¶
reStructuredtext是Sphinx使用的默认明文标记语言。 本节简要介绍reStructuredtext（reST）概念和语法，旨在为作者提供足够的信息来高效地创作文档。 由于reStructuredtext被设计为一种简单、不引人注目的标记语言，因此这不会需要太长时间。
参见
权威 reStructuredText User Documentation .本文档中的“ref”链接链接到reStructured文本参考中各个结构的描述。
段落¶
该段 (ref ）是reStructuredtext文档中最基本的块。段落只是由一个或多个白线分隔的文本块。与Python中一样，缩入在reStructuredtext中很重要，因此同一段落的所有行必须左对齐到相同的缩入级别。
内联标记¶
标准的reStructured文本内联标记非常简单：使用
一个星号：
*text*用于强调(斜体)，两个星号：
**text**用于强调(粗体)，以及反引号：
``text用于代码示例的``。
如果连续文本中出现星号或反引号，并可能与内联标记分隔符混淆，则必须使用反斜杠对其进行转义。
请注意此标记的一些限制：
它可以不嵌套，
内容不能以空格开头或结尾：
* text*是错误的，必须用非单词字符将其与周围的文本分开。使用反斜杠转义空格来解决此问题：
thisis\ *one*\ word。
这些限制可能会在未来版本的Docutils中取消。
还可以用角色替换或扩展其中一些内联标记。参阅 角色 for more information.
列表和类似报价的块¶
列表标记 (ref )是很自然的：只需在段落开头加一个星号并适当缩进即可。编号列表也是如此；也可以使用 # 签名：：
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
嵌套列表是可能的，但请注意，它们必须与父列表项之间用空行分隔：：
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
定义列表 (ref )按如下方式创建：
term (up to a line of text)
Definition of the term, which must be indented
and can even consist of multiple paragraphs
next term
Description.
请注意，该术语不能有超过一行文本。
被引用的段落 (ref )是通过缩进它们而不是周围段落来创建的。
线条块 (ref )是保留换行符的一种方式：：
| These lines are
| broken exactly like in
| the source file.
还有几个更特殊的区块可用：
文字块¶
文字代码块 (ref )以特殊标记结尾的段落作为引言 :: 。文字块必须缩进(与所有段落一样，与周围段落用空行隔开)：：
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
的处理方式 :: 标记器很聪明：
如果它作为一个单独的段落出现，则该段落将完全从文件中删除。
如果前面有空格，则删除该标记。
如果它前面有非空格，则该标记将被单个冒号替换。
这样，上面示例第一段中的第二句话将呈现为“下一段是代码样本：”。
可以在文档范围内为这些文字块启用代码突出显示。 highlight 指令，并在项目范围内使用 highlight_language 配置选项。这个 code-block 指令可用于在逐个块的基础上设置突出显示。这些指令将在后面讨论。
Doctest块¶
Doctest块 (ref )是被剪切并粘贴到文档字符串中的交互式Python会话。它们不需要 literal blocks 语法。Doctest块必须以空行结束，并且应该 not 以未使用的提示符结束：：
>>> 1 + 1
2
表格¶
For grid tables (ref), you have to "paint" the cell grid yourself. They look like this:
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
Simple tables (ref) are easier to write, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
支持另外两种语法： CSV tables 和 List tables 。他们使用一种 explicit markup block 。参考 表格 以获取更多信息。
超链接¶
外部链接¶
使用 `Link text <https://domain.invalid/>`_ 用于内联Web链接。如果链接文本应该是网址，则根本不需要特殊标记，解析器会在普通文本中查找链接和邮件地址。
重要
链接文本和URL的开头<之间必须有空格。
您还可以将链接定义和目标定义分开 (ref )，如下所示：
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
内部链接¶
内部链接是通过Sphinx提供的特殊reStructuredtext角色完成的，请参阅有关特定标记的部分， 交叉引用任意位置 .
分段¶
节标题 (ref )通过使用标点符号对部分标题加下划线(或可选加上划线)来创建，至少与文本：：
=================
This is a heading
=================
通常情况下，不会将标题级别分配给某些字符，因为结构是根据标题的顺序确定的。但是，此约定用于 Python Developer's Guide for documenting 你可以遵循这一点：
#带上划线，用于零件*带上划线，用于章节=对于各节-适用于小节^适用于小节"对于段落
当然，您可以自由地使用自己的标记字符（请参阅reStructuredtext文档），并使用更深的嵌套级别，但请记住，大多数目标格式（HTML、LaTeX）支持的嵌套深度有限。
字段列表¶
字段列表 (ref )是这样标记的字段序列：：
:fieldname: Field content
它们通常在Python文档中使用：
def my_function(my_arg, my_other_arg):
"""A function just for me.
:param my_arg: The first of my arguments.
:param my_other_arg: The second of my arguments.
:returns: A message (just for me, of course).
"""
Sphinx扩展了标准的docutils行为，并拦截在文档开头指定的字段列表。参考 字段列表 以获取更多信息。
角色¶
角色或“自定义解释文本角色” (ref ）是一个内联的显式标记。这意味着所附文本应该以特定的方式解释。 Sphinx使用此功能来提供语义标记和标识符的交叉引用，如相应部分所述。 一般语法是 :rolename:`content `.
Docutils支持以下角色：
emphasis -- equivalent of
*emphasis*strong -- equivalent of
**strong**literal -- equivalent of
``literal``subscript --下标文本
superscript --上标文本
title-reference -图书、期刊和其他材料的标题
参考 角色 用于Sphinx添加的角色。
显式标记¶
“显式加价” (ref ）用于reStructuredtext中，用于大多数需要特殊处理的结构，例如脚注、特别突出显示的段落、评论和通用指令。
显式标记块以一行开头 .. 后跟空格，并以相同缩进级别的下一段结束。(显式标记和正常段落之间需要有一个空行。这一切听起来可能有点复杂，但当你写它的时候，它已经足够直观了。)
指令¶
一项指令 (ref ）是显式标记的通用块。除了角色之外，它还是reStructuredtext的扩展机制之一，Sphinx大量使用了它。
Docutils支持以下指令：
警告： attention ， caution ， danger ， error ， hint ， important ， note ， tip ， warning 和通用的 admonition 。(大多数主题只会特别设置“注意”和“警告”的样式。)
图片：
其他主体元素：
contents (本地目录，即仅用于当前文件的目录)
container (具有自定义类的容器，用于生成外部
<div>(以Html表示)rubric (与文件切分无关的标题)
parsed-literal (支持内联标记的文字块)
epigraph (带有可选归属行的块引用)
highlights ， pull-quote (使用自己的类属性阻止引号)
compound (复合段落)
特殊表格：
table (附标题的表格)
csv-table (由逗号分隔值生成的表)
list-table (从列表列表生成的表)
特别指令：
Html详细信息：
影响加价：
default-role (设置新的默认角色)
role (创建新角色)
由于这些只针对每个文件，因此最好使用Sphinx的工具来设置
default_role。
中描述了由Sphinx添加的指令 指令 。
基本上，指令由名称、参数、选项和内容组成。(请记住此术语，它将在描述定制指令的下一章中使用。)在此示例中，：：
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function 是指令名称。这里给它提供了两个参数，第一行和第二行的其余部分以及一个选项 module (如您所见，选项位于紧跟在参数后面的行中，并由冒号表示)。选项必须缩进到与指令内容相同的级别。
指令内容跟随在空行之后，并且相对于指令开始缩进，或者如果存在选项，则缩进与选项相同的量。
请注意，缩进不是固定数量的空格，例如三个，而是任意数量的空格。当在整个文档中使用固定缩进时，这可能会令人惊讶，并且可能会对对空格敏感的指令产生影响。比较：
.. code-block::
:caption: A cool example
The output of this line starts with four spaces.
.. code-block::
The output of this line has no spaces at the beginning.
在第一个代码块中，选项行将内容的缩进固定为三个空格，因此内容以四个空格开始。在后者中，缩进由内容本身固定为七个空格，因此它不是以空格开始的。
图片¶
reStructuredtext支持图像指令 (ref ），用法如下：：
.. image:: gnu.png
(options)
在Sphinx中使用时，给定的文件名(此处 gnu.png )必须是相对于源文件的，或者是绝对的，这意味着它们是相对于顶级源目录的。例如，文件 sketch/spam.rst 可以参考图片 images/spam.png AS ../images/spam.png 或 /images/spam.png 。
Sphinx会自动将图像文件复制到建筑输出目录的子目录中(例如 _static 用于HTML输出的目录。)
解释图像大小选项 (width 和 height )如下所示：如果大小没有单位或单位是像素，则仅支持像素的输出通道才会考虑给定的大小。其他单位(如 pt 用于点数)将用于HTML和LaTeX输出(后者取代 pt 通过 bp 因为这是特克斯单位，所以 72bp=1in )。
Sphinx扩展了标准的docutils行为，允许使用星号作为扩展名：：
.. image:: gnu.*
然后，Sphinx搜索与提供的模式匹配的所有图像，并确定其类型。然后，每个建造者从这些候选人中选出最好的形象。例如，如果文件名 gnu.* 并提供了两个文件 gnu.pdf 和 gnu.png 存在于源代码树中时，LaTeX构建器将选择前者，而HTML构建器将倾向于后者。支持的映像类型和选择优先级定义在 构建器 。
请注意，图像文件名不应包含空格。
在 0.4 版本发生变更: 添加了对以星号结尾的文件名的支持。
在 0.6 版本发生变更: 图像路径现在可以是绝对路径。
在 1.5 版本发生变更: LaTeX目标支持像素(默认为 96px=1in )。
脚注¶
有关脚注 (ref )，使用 [#name]_ 要标记脚注位置，并在文档底部的“脚注”标题后面添加脚注正文，如下所示：
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
您还可以对脚注进行显式编号 ([1]_ )或使用不带名称的自动编号脚注 ([#]_ )。
引文¶
标准重新结构化文本引用 (ref ）得到支持，其附加功能是“全球”，即所有引用都可以从所有文件引用。 这样使用它们：：
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引文用法类似于脚注用法，但标签不是数字或以 # 。
替换¶
reStructuredtext支持“替换” (ref ），它们是文本中引用的文本片段和/或标记 |name| .它们被定义为带有显式标记块的脚注，如下所示：
.. |name| replace:: replacement *text*
或者这个：：
.. |caution| image:: warning.png
:alt: Warning!
看到 reStructuredText reference for substitutions 有关详细信息
如果您希望使用某些替换来替换所有文档，请将它们放入 rst_prolog 或 rst_epilog 或将它们放入单独的文件中，并将其包含在要在其中使用它们的所有文档中。 include 指令。(请确保为包含文件提供与其他源文件不同的文件扩展名，以避免Sphinx将其视为独立文档。)
Sphinx定义了一些默认替换，请参见 替换 。
HTML元数据¶
这个 meta 指令允许指定 metadata element Sphinx文档页面的。例如，指令：：
.. meta::
:description: The Sphinx documentation builder
:keywords: Sphinx, documentation, builder
将生成以下HTML输出：
<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">
此外，Sphinx会将meta指令中指定的关键字添加到搜索索引中。因此， lang 属性，则考虑元元素。例如，指令：：
.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
将以下单词添加到具有不同语言配置的生成的搜索索引中：
pleasefindthiskey，pleasefindthiskeytoo至 English 构建；bittediesenkeyfinden至 German 构建；backup来构建所有语言版本。
信源编码¶
由于在reStructuredText中包含特殊字符（如em破折号或版权标志）的最简单方法是直接将它们写成Unicode字符，因此必须指定编码。 Sphinx假定源文件默认使用UTF-8编码;您可以使用 source_encoding 配置值。
我明白了¶
在创作reStructuredText文档时，通常会遇到一些问题：
Separation of inline markup: 如上所述，内联标记范围必须用非单词字符与周围的文本分开，您必须使用反斜杠转义空格来绕过这一点。看见 the reference 详情请看。
No nested inline markup: 像这样的东西
*see :func:`foo`*是不可能的。
评论¶
每个不是有效标记构造的显式标记块(如上面的脚注)都被视为注释 (ref )。例如：：
.. This is a comment.您可以在注释开始后缩进文本以形成多行注释：：