RST初级读本¶
reStructuredText是Sphinx使用的默认纯文本标记语言。 本节简要介绍reStructuredText(reST)概念和语法，旨在为作者提供足够的信息，以高效地编写文档。 由于reST旨在成为一种简单，不显眼的标记语言，因此这不会花费太长时间。
参见
权威的 reStructuredText用户文档 。本文档中的”ref”链接链接到reST参考中各个构造的描述。
行内标记¶
标准的reST行内标记非常简单: 使用
一个星号:
*text*用于强调( 斜体 )，两个星号:
**text**用于强调( 粗体 )反引号:
``text``代码示例(code)。
如果星号或反引号出现在正在运行的文本中并且可能与行内标记分隔符混淆，则必须使用反斜杠对其进行转义。
请注意此标记的一些限制:
它不能嵌套，
内容无法以空格开头或结尾:
* text*错误，必须通过非单词字符将其与周围文本分开。使用反斜杠转义空格来解决这个问题:
thisis\ *one*\ word。
在将来的docutils版本中可能会取消这些限制。
也可以使用角色替换或扩展此行内标记。有关更多信息，请参阅 角色 。
列表和引用样块¶
列表标记(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.
处理 :: 标记是聪明的:
如果它作为自己的段落出现，则该段落完全不在文档中。
如果前面有空格，则删除标记。
如果前面是非空格，则标记将替换为单个冒号。
这样，上面例子的第一段中的第二句将呈现为 “The next paragraph is a code sample:”。
可以使用 highlight 指令在文档范围内为这些文字块启用代码突出显示，并在项目范围内使用 highlight_language 配置选项。 code-block 指令可用于逐块设置突出显示。这些指令将在后面讨论。
Doctest块¶
Doctest块(ref)是切换并粘贴到文档字符串中的交互式Python会话。它们不需要 literal blocks 语法。 doctest块必须以空行结束，并且 不 以未使用的提示结束:
>>> 1 + 1
2
表¶
对于 grid tables (ref)，你必须自己”绘制”单元格网格。他们看起来像这样:
+------------------------+------------+----------+----------+
| 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 | ... | ... | |
+------------------------+------------+----------+----------+
简单表 (ref)更容易编写，但有限制: 它们必须包含多行，并且第一列单元格不能包含多行。他们看起来像这样:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
支持另外两种语法: CSV表 和 列表 。他们使用 显式标记块 。有关更多信息，请参阅 表格。
超链接¶
章节标题¶
通过使用标点符号为节标题(ref)加下划线(上划线可选)来创建节标题, 至少与文本一样长:
=================
This is a heading
=================
通常，没有为某些字符分配标题级别，因为结构是从标题的连续性确定的。但是，这个约定在 Python的样式指南中用于记录 ，您可以遵循:
#有上线，用于编*有上线，用于章=, 用于节-, 用于小节^, 用于子小节", 用于款
当然，您可以自由使用自己的标记字符(请参阅reST文档)，并使用更深层次的嵌套级别，但请记住，大多数目标格式(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 – 相当于
*emphasis*strong – 相当于
**strong**literal – 相当于
``literal``subscript – 下标文字
superscript – 上标文字
title-reference – 用于书籍，期刊和其他材料的标题
请参阅 角色 ，了解Sphinx添加的角色。
显式标记¶
“显式标记”(ref)在reST中用于大多数需要特殊处理的构造，例如脚注，特别突出显示的段落，注释和泛型指令。
显式标记块以一行开头，以”..”开头，后跟空格，并在相同的缩进级别由下一段终止。 (显式标记和普通段落之间需要有一个空行。这可能听起来有点复杂，但是当你写它时它足够直观。)
指令¶
指令(ref)是显式标记的通用块。与角色一起，它是reST的扩展机制之一，并且Sphinx大量使用它。
Docutils支持以下指令:
忠告: 注意(attention)，警告(caution)，危险(danger)，错误(error)，暗示(hint)，重要(important)，注释(note) ，技巧(tip)，警告(warning) 和泛型 警告(admonitions) 。 (大多数主题仅限于 “note” 和 “warning” 。)
图片:
额外的 body 元素:
contents (本地，即仅当前文件，目录)
container (一个带有自定义类的容器，用于在HTML中生成外部
<div>)rubric (与文档切片无关的标题)
parsed-literal (支持行内标记的文字块)
epigraph (带有可选归因线的块引用)
highlight ， pull-quote (带有自己的class属性的块引号)
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 (如你所见，选项在紧跟在参数后面的行中给出并由冒号表示) 。选项必须缩进到与指令内容相同的级别。
指令内容在空白行后面，并相对于指令开始缩进。
图片¶
reST支持一个image指令(ref)，像这样使用:
.. image:: gnu.png
(options)
在Sphinx中使用时，给定的文件名(此处为 gnu.png )必须相对于源文件，或者绝对意味着它们相对于顶级源目录。例如，文件 sketch/spam.rst 可以将图像 images/spam.png 写为 ../images/spam.png 或 /images/spam.png 。
Sphinx会自动将图像文件复制到构建的输出目录的子目录中(例如，用于HTML输出的 _static 目录。)
图像大小选项( width 和 height )的解释如下:如果大小没有单位或单位是像素，则只有支持像素的输出通道才会考虑给定大小。其他单位(如点的 pt )将用于HTML和LaTeX输出(后者用 bp 替换 pt ，因为这是TeX单元，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]_ 标记脚注位置，并在 “Footnotes ” 标题后添加脚注主体在文档底部，像这样:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
您还可以明确编号脚注([1]_)或使用不带名字的自动编号脚注([＃]_)。
引文¶
支持标准reST引用(ref)，其附加功能是 “global” ，即所有引用都可以从所有文件引用。像这样使用它们:
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引用用法类似于脚注用法，但标签不是数字或以”＃”开头。
替换¶
reST支持 “substitutions” (ref)，它们是文本中按 |name| 引用的文本和/或标记。它们被定义为带有显式标记块的脚注，如下:
.. |name| replace:: replacement *text*
或这个:
.. |caution| image:: warning.png
:alt: Warning!
有关详细信息，请参阅 reST参考替换 。
如果要对所有文档使用一些替换，请将它们放入 rst_prolog 或 rst_epilog 或将它们放入单独的文件中，并将其包含在要使用它们的所有文档中，使用 include 指令。 (确保为include文件提供与其他源文件不同的文件扩展名，以避免Sphinx将其作为独立文档发现。)
Sphinx定义了一些默认替换，请参阅 替换 。
评论¶
每个显式标记块都不是有效的标记结构(如上面的脚注)，它被视为注释(ref)。例如:
.. This is a comment.
您可以在评论开始后缩进文本以形成多行注释:
..
This whole indented block
is a comment.
Still in the comment.
源编码¶
由于在reST中包含特殊字符(例如em破折号或版权符号)的最简单方法是将它们直接写为Unicode字符，因此必须指定编码。 Sphinx默认假设源文件以UTF-8编码;你可以用 source_encoding 配置值来改变它。