基本语法¶
指令(Directives)¶
这里的指令是指 RST 语言定义的指示如何生成目标文件的命令定义格式。Sphinx对它进行了扩展。
指令的语法如下,它由 “..” + “Space” + “指令类型” + “::” + “Space” + “指令块” 构成。
RST 语言对空格和空行的使用具有严格的定义,它们是指令的一部分,需要注意。
- “.” 是指英文的句号.
- “Sapce” 是指一个空格.
- “:” 是英文的冒号.
0 1 2 3 4 | +-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block |
| |
+-------------------------------+
|
指令块包含三部分,对于不同的指令,它们可能是强制的,也可能是可选的:
- 指令参数 (Directive arguments).
- 指令选项 (Directive options).
- 指令所作用的内容 (Directive content).
以 image 指令为例,它支持一个参数,且是必须的(required)。选项是可选的,不需要指令内容。
0 1 2 | Directive Arguments: One, required (image URI).
Directive Options: Possible.
Directive Content: None.
|
image 指令示例:
0 1 2 3 4 5 6 | .. image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right
:target: www.xxx.xx
|
段落(Paragraphs)¶
段落是文章的基本组成单位,分段不需要任何标记的帮助,空行分割不同的段落。例如:
这是第一个段落。
前边有空行,所以这里是第二个段落。
0 1 2 | 这是第一个段落。尽管进行了换行,该行依然属于第一个段落。
前边有空行,所以这里是第二个段落。
|
行内标记¶
- 强调,使用一个星号,显示为斜体:emphasis
- 加强,使用两个星号,显示为粗体: strong
- 代码示例,使用两个反引号:
literal
- 下标显示:H2O
- 上标显示:E = mc2
0 1 2 3 4 | - 强调,使用一个星号,显示为斜体:*emphasis*
- 加强,使用两个星号,显示为粗体: **strong**
- 代码示例,使用两个反引号:``literal``
- 下标显示:H\ :sub:`2`\ O
- 上标显示:E = mc\ :sup:`2`
|
RST 不可同时支持斜体和加粗特定,这是它的一个小缺陷。
如果文本部分包含标记所使用的标记字符,则需要加反斜杠进行转义:
转义显示:*text*
0 | 转义显示:\*text\*
|
硬换行¶
有些编辑器支持换行显示,尽管文本还在同一行,但是编辑时可以换行显示,但是有些编辑器不支持,为何在书写时把一个长行方便的显示出来,需要硬换行。在行尾添加 “\” 既可实现硬换行,它们被解析时,作为一行对待。
如果不使用硬换行符,而输入回车换行,那么换行符会生成一个空格,由于英文单词间有空格,所以英文的 .rst 文件奇妙的利用换行来规避了该问题。
不必说碧绿的菜畦,光滑的石井栏,高大的皂荚树,紫红的桑葚;也不必说鸣蝉在树叶里长吟,肥胖的黄蜂伏在菜花上,轻捷的叫天子(云雀)忽然从草间直窜向云霄里去了。单是周围的短短的泥墙根一带,就有无限趣味。油蛉在这里低唱,蟋蟀们在这里弹琴。翻开断砖来,有时会遇见蜈蚣;还有斑蝥,倘若用手指按住它的脊梁,便会啪的一声,从后窍喷出一阵烟雾。
0 1 2 3 | 不必说碧绿的菜畦,光滑的石井栏,高大的皂荚树,紫红的桑葚;也不必说鸣蝉在树叶里长吟,\
肥胖的黄蜂伏在菜花上,轻捷的叫天子(云雀)忽然从草间直窜向云霄里去了。单是周围的短短的泥\
墙根一带,就有无限趣味。油蛉在这里低唱,蟋蟀们在这里弹琴。翻开断砖来,有时会遇见蜈蚣;还\
有斑蝥,倘若用手指按住它的脊梁,便会啪的一声,从后窍喷出一阵烟雾。
|
列表¶
无序列表(Bullet lists)¶
以”*”, “+”, “-“, “•”, “‣”,或”⁃”加空格开头,具有相同缩进的行作为列表处理。通常使用”-“。
- 列表表项1
- 列表表项2
- 列表表项3
0 1 2 | - 列表表项1
- 列表表项2
- 列表表项3
|
列表可以通过缩进进行嵌套,注意子项前必须留有空行:
- 列表表项1
- 子表项1
- 子表项2
0 1 2 3 | - 列表表项1
- 子表项1
- 子表项2
|
枚举列表(Enumerated lists)¶
枚举列表可以给表项进行编序,有下几种序号格式:
- 阿拉伯数字:1,2,3,…
- 大写字母:A,B,C,…
- 小写字母:a,b,c,…
- 大写罗马数字:I, II, III, IV, …
- 小写罗马数字:i, ii, iii, iv, …
- 列表表项1
- 列表表项2
0 1 | a. 列表表项1
b. 列表表项2
|
可以使用”#”号实现自动编序。
- 列表表项1
- 列表表项2
0 1 | a. 列表表项1
#. 列表表项2
|
自动编序支持以下几种格式的前缀:
- 普通前缀: “1.”, “A.”, “a.”, “I.”, “i.”
- 带小括号的前缀: “(1)”, “(A)”, “(a)”, “(I)”, “(i)”
- 带右括号的前缀: “1)”, “A)”, “a)”, “I)”, “i)”
列表项多列显示¶
多列显示,只支持无序表(Bullet Lists)。
|
|
0 1 2 3 4 5 | .. hlist::
:columns: 2
- 列表表项1
- 列表表项2
- 列表表项3
- 列表表项4
|
链接¶
脚注和引用¶
脚注(Footnotes)¶
[1] 参考脚注1, [2] 参考脚注2,[3] 参考脚注3,可以直接填入数字,也可以使用”#”自动为脚注编序。
[1] | 这是脚注1. |
[2] | 这是脚注2. |
[3] | 这是脚注3. |
0 1 2 3 4 | [#]_ 参考脚注1, [#]_ 参考脚注2.
.. [#] 这是脚注1.
.. [#] 这是脚注2.
.. [3] 这是脚注3.
|
引用(Citations)¶
与脚注类似,可以全局使用,只需直接使用引用的名字:
引用参考的内容通常放在页面结尾处,比如 [One],[Two]
[One] | 参考引用一 |
[Two] | 参考引用二 |
0 1 2 3 | 引用参考的内容通常放在页面结尾处,比如 [One]_,[Two]_
.. [One] 参考引用一
.. [Two] 参考引用二
|
引用图片¶
可以引用本地图片,也可以指定图片的URL。
0 | .. image:: _static/test.png
|
图片也可以指向超链接:
0 1 | .. image:: _static/test.png
:target: http://www.baidu.com
|
image 指令不能定义标题。如果需要请使用 figure 指令。
提示(Admonitions)¶
用一段话进行提示,告警等。支持的提示类型有:
|
|
|
Note
这里书写提示信息。
Warning
这里书写警告信息。
自定义
自定义消息提示。
0 1 2 3 4 5 6 7 8 | .. note::
这里书写提示信息。
.. warning::
这里书写警告信息。
.. admonition:: 自定义
自定义消息提示。
|
术语表(Glossary)¶
术语可以有多个名称,对应一条解释。
- 术语
- 这里是对术语的解释说明。
- DNA
- 脱氧核糖核酸
- 脱氧核糖核酸又称去氧核糖核酸,是一种生物大分子,可组成遗传指令,引导生物发育与生命机能运作。
0 1 2 3 4 5 6 7 8 | .. glossary::
术语
这里是对术语的解释说明。
DNA
脱氧核糖核酸
脱氧核糖核酸又称去氧核糖核酸,是一种生物大分子,可组成遗传指令,
引导生物发育与生命机能运作。
|
代用(Substitutions)¶
代用类似 C 语言中的宏定义,可以对代用符号进行全局替换。
这里的代用符号 名称 将被替换为中文名称。
这里的代用符号 将被替换为图片。
0 1 2 3 4 5 | 这里的代用符号 |name| 将被替换为中文名称。
这里的代用符号 |caution| 将被替换为图片。
.. |name| replace:: 名称
.. |caution| image:: _static/warning.png
|